cqwiki cqadmino_mdw2 http://www.cqadmin.org/wiki/Main_Page MediaWiki 1.32.0 first-letter Media Special Talk User User talk cqwiki cqwiki talk File File talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk 14 4 6 2008-12-07T00:08:16Z 75.190.182.154 0 New page: ClearQuest Email Notification Package [[Category:ClearQuest]] wikitext text/x-wiki ClearQuest Email Notification Package [[Category:ClearQuest]] 734a34442e2c5aede428b1137ee7cf0d0de6bb51 7 6 2010-11-05T00:28:06Z Paul 1 1 revision wikitext text/x-wiki ClearQuest Email Notification Package [[Category:ClearQuest]] 734a34442e2c5aede428b1137ee7cf0d0de6bb51 14 3 4 2008-12-07T22:41:16Z 75.190.182.154 0 wikitext text/x-wiki ClearQuest related materials [[Category:Rational]] c2efd7b483c3a0ae4525a561b8c81e46747844f2 5 4 2010-11-05T00:28:06Z Paul 1 1 revision wikitext text/x-wiki ClearQuest related materials [[Category:Rational]] c2efd7b483c3a0ae4525a561b8c81e46747844f2 0 6 10 2008-12-07T23:09:12Z Paul 1 New page: <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detaile... wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === Click [http://cqadmin.org/data/EmailNotification_Package.zip here] to download the latest version of the package. === Delivery Script === [http://cqadmin.org/data/EmailNotification_DeliveryScript.zip Simple delivery script] is required for queue delivery mode, so download is optional. === Timed Notification Script === [http://cqadmin.org/data/TimedNotification.zip Timed notification script] is also optional. Please refer to [[Timed_Notification | Timed Notification]] page for more information. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3e84752e1f73664338dbda6477574a3fc977cf1a 11 10 2010-11-05T00:28:07Z Paul 1 1 revision wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === Click [http://cqadmin.org/data/EmailNotification_Package.zip here] to download the latest version of the package. === Delivery Script === [http://cqadmin.org/data/EmailNotification_DeliveryScript.zip Simple delivery script] is required for queue delivery mode, so download is optional. === Timed Notification Script === [http://cqadmin.org/data/TimedNotification.zip Timed notification script] is also optional. Please refer to [[Timed_Notification | Timed Notification]] page for more information. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3e84752e1f73664338dbda6477574a3fc977cf1a 0 9 16 2008-12-10T03:18:43Z Paul 1 New page: =Applying Package to a Stateless record type= You cannot apply any package to stateless record type using Package Wizard. Fortunately, command line tool ''packageutil'' does not have such... wikitext text/x-wiki =Applying Package to a Stateless record type= You cannot apply any package to stateless record type using Package Wizard. Fortunately, command line tool ''packageutil'' does not have such restrictions * Apply package to stateless record type from command line <source lang="bash"> packageutil enablerecord -dbset <connection> <login> <admin> \ <schema_name> EmailNotification <record_type> -nocheckin </source> --- Modifying work in progress on revisiioon xxx of schema 'Your_Schema_Name' +++ Enabled record type 'record_type' for version '1.2' of package 'EmailNotification' --- Saved work in progress on revision 22 of schema 'Your_Schema_Name' * Open schema in designer to verify changes. * Checkin schema and upgrade user databases. '''Note:''' Any action of Base type cause a delay in stateless record type actions (even simple one). The delay can be significant if you have hundreds of thousands records and need to import them on regular basis. All operations seems to be about 7 times slower (with BASE actions vs without it). [[Category:Email_Notification_Package]] d312d8be8f7f856081bd7cfe978928ea4d161633 17 16 2010-11-05T00:28:07Z Paul 1 1 revision wikitext text/x-wiki =Applying Package to a Stateless record type= You cannot apply any package to stateless record type using Package Wizard. Fortunately, command line tool ''packageutil'' does not have such restrictions * Apply package to stateless record type from command line <source lang="bash"> packageutil enablerecord -dbset <connection> <login> <admin> \ <schema_name> EmailNotification <record_type> -nocheckin </source> --- Modifying work in progress on revisiioon xxx of schema 'Your_Schema_Name' +++ Enabled record type 'record_type' for version '1.2' of package 'EmailNotification' --- Saved work in progress on revision 22 of schema 'Your_Schema_Name' * Open schema in designer to verify changes. * Checkin schema and upgrade user databases. '''Note:''' Any action of Base type cause a delay in stateless record type actions (even simple one). The delay can be significant if you have hundreds of thousands records and need to import them on regular basis. All operations seems to be about 7 times slower (with BASE actions vs without it). [[Category:Email_Notification_Package]] d312d8be8f7f856081bd7cfe978928ea4d161633 0 8 14 2008-12-11T02:11:20Z Paul 1 /* Select EmailNotification 1.3 package from the list of installed packages */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you created backup to be able to roll back the change if necessary. == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.3 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] Please also check [[Applying_Package_to_Stateless_Records| applying package to a stateless record type]] section. == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Open ClearQuest and configure package according to package configuration instructions == submit properties: [[Image:submit_properties.jpg | none ]] === Set mail_host = your SMTP host === [[Image:email_host.jpg]] === Set email_enabled = 1 === Second mandatory property besides mail_host. Notifications will not be generated is the property is not set! === Set other properties if required === Check other available properties in the [[Package_configuration | configuration guide]] === Create simple notification rule === [[Image:submit_Email_Notification_Rule.jpg]] For example, a simple rule to notify submitter that Defect is closed: [[Image:en_1.jpg]] [[Image:en_2.jpg]] [[Image:en_3.jpg]] === Test created notification rule === [[Category:Email_Notification_Package]] c7c4194d08b7ee43f83827b2fb178f7ae5b16372 15 14 2010-11-05T00:28:07Z Paul 1 1 revision wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you created backup to be able to roll back the change if necessary. == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.3 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] Please also check [[Applying_Package_to_Stateless_Records| applying package to a stateless record type]] section. == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Open ClearQuest and configure package according to package configuration instructions == submit properties: [[Image:submit_properties.jpg | none ]] === Set mail_host = your SMTP host === [[Image:email_host.jpg]] === Set email_enabled = 1 === Second mandatory property besides mail_host. Notifications will not be generated is the property is not set! === Set other properties if required === Check other available properties in the [[Package_configuration | configuration guide]] === Create simple notification rule === [[Image:submit_Email_Notification_Rule.jpg]] For example, a simple rule to notify submitter that Defect is closed: [[Image:en_1.jpg]] [[Image:en_2.jpg]] [[Image:en_3.jpg]] === Test created notification rule === [[Category:Email_Notification_Package]] c7c4194d08b7ee43f83827b2fb178f7ae5b16372 0 11 20 2008-12-11T02:59:44Z Paul 1 /* What options do we have? */ wikitext text/x-wiki ==Why the package was created?== I was not satisfied with the functionality provided by the standard solution. Let me give you a brief overview of ther features that we (do not) have in the standard package distributed with ClearQuest. == Top three ''features'' of the standard package that I do NOT like== === Inflexibility === Notification configuration is limited to selection of fields that are included in the message. Can you create custom subject with pre-configured text, or provide detailed instructions on why he or she received the notification and what needs to be done? Yes, you can, but you would need to create a field with solely purpose: to keep the text to be included in the message. I do not think that it is a great idea to extend data structure with a bunch of unnecessary fields. === Unreliability === If notification is not sent due to mail service unavailability, client’s misconfiguration, antivirus block, or any other reason – it is lost. You will never be able to find why it was not delivered. === Terrible configuration === Notification settings need to be configured on every single client. It is not too bad when you use CQWeb only, but imagine what it cost you when you have thousand of fat clients installed. How simple would it be to change settings, for example, smtp host? When you enabled notification on a client, it is enabled for all databases accessed from the client. It does not matter, whether it is a test or production database – it makes it very complicated to develop and test notification rules. Finally, a user could simply turn off email notification on his or her machine, and you can do nothing about it. Personally, I do not understand why the vendor of so powerful tool as ClearQuest cannot offer something better for their customers.<br /><br /> ==What options do we have?== You know all disadvantages above even better than me. I do not use standard package for years now. You might be frustrated, but what are the options do you have? * You can continue using standard package and simply decline any enhancements requested by your customers, since they cannot be implemented. The advantage is that you have supported solution. Unfortunately, it is the only advantage. * Another option could be to develop your own, custom made, notification hook. (You might be already have one?) The benefit is that it is your own solution, but do you need to update ClearQuest schema and upgrade user databases when any change is required? Is it easy to deploy it to a new schema? Is it easy to support in multiple schemas? I think, you know it better. * Fortunately, there is one more option that you can try: an alternative [[ClearQuest_Email_Notification_Package | Email Notification package]]. <br /><br /> [[Category:Email_Notification_Package]] cf55f1ae8d890e77353b2bd3ff92a9fe473d7be2 21 20 2010-11-05T00:28:08Z Paul 1 1 revision wikitext text/x-wiki ==Why the package was created?== I was not satisfied with the functionality provided by the standard solution. Let me give you a brief overview of ther features that we (do not) have in the standard package distributed with ClearQuest. == Top three ''features'' of the standard package that I do NOT like== === Inflexibility === Notification configuration is limited to selection of fields that are included in the message. Can you create custom subject with pre-configured text, or provide detailed instructions on why he or she received the notification and what needs to be done? Yes, you can, but you would need to create a field with solely purpose: to keep the text to be included in the message. I do not think that it is a great idea to extend data structure with a bunch of unnecessary fields. === Unreliability === If notification is not sent due to mail service unavailability, client’s misconfiguration, antivirus block, or any other reason – it is lost. You will never be able to find why it was not delivered. === Terrible configuration === Notification settings need to be configured on every single client. It is not too bad when you use CQWeb only, but imagine what it cost you when you have thousand of fat clients installed. How simple would it be to change settings, for example, smtp host? When you enabled notification on a client, it is enabled for all databases accessed from the client. It does not matter, whether it is a test or production database – it makes it very complicated to develop and test notification rules. Finally, a user could simply turn off email notification on his or her machine, and you can do nothing about it. Personally, I do not understand why the vendor of so powerful tool as ClearQuest cannot offer something better for their customers.<br /><br /> ==What options do we have?== You know all disadvantages above even better than me. I do not use standard package for years now. You might be frustrated, but what are the options do you have? * You can continue using standard package and simply decline any enhancements requested by your customers, since they cannot be implemented. The advantage is that you have supported solution. Unfortunately, it is the only advantage. * Another option could be to develop your own, custom made, notification hook. (You might be already have one?) The benefit is that it is your own solution, but do you need to update ClearQuest schema and upgrade user databases when any change is required? Is it easy to deploy it to a new schema? Is it easy to support in multiple schemas? I think, you know it better. * Fortunately, there is one more option that you can try: an alternative [[ClearQuest_Email_Notification_Package | Email Notification package]]. <br /><br /> [[Category:Email_Notification_Package]] cf55f1ae8d890e77353b2bd3ff92a9fe473d7be2 0 12 22 2008-12-11T04:11:37Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> lets define two functions in database properties:<br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> [[Category:Email_Notification_Package]] 229701ea149c80d843375b290bb99d17cbc6499c 23 22 2010-11-05T00:28:08Z Paul 1 1 revision wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> lets define two functions in database properties:<br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> [[Category:Email_Notification_Package]] 229701ea149c80d843375b290bb99d17cbc6499c 0 10 18 2008-12-11T11:56:18Z Paul 1 /* OR provide filter criteria for dynamic query */ wikitext text/x-wiki =Timed Notification= == What does Timed Notification mean? == Sometimes we would like to implement notifications that are not triggered by particular action. You might need a reminder that defect approached a resolution deadline, or that a trouble ticket passed due date, was not implemented in time frame required by the Service Level Agreement, was not assigned for implementation in a reasonable time frame. A call such kind of requests Timed Notifications or Reminders. == How Timed Notifications / Reminders are implemented? == There are two parts of the complicated task # find records that are eligible for notification # trigger notifications based on information in selected records === How to find records? === To make it flexible, the selection process is implemented in two phases ==== Initial records selection ==== It is limiting scope based on simple criteria the can be used in a SQL Query to retrieve records. For example, you can limit records based on record type, current state, severity, assignment, etc. Timed Notification script offers you two possibilities: # create a ClearQuest query, and save it in the public workspace # specify criteria to create the query dynamically during the execution ==== Final selection ==== In addition, records can be filtered based on Email Notification Rule ''Condition'' field. It is performed during evaluation of notification rules on the record set selected on the previous step. Rules evaluation is expensive process that is why it very is important to have good initial record selection. === Triggering notifications === Since we are using extremely customizable email notification rules for other actions, it makes sense to use the same functionality, and keep timed notification rules at the same place. Regular notifications are triggered by ''actions'', timed notifications - by ''pseudo-actions''. It means that in reality no action is executed, but the script evaluates email notification rules on selected records in the same way as it would be done if the real action would be invoked. If you noticed, selection of actions on Email Notification Rule record is not limited to actions defined for the record type, and it is done on purpose: you can specify there non-existent, '''pseudo-action''' name. To make all thins working, you just need to * create a notification rule, using ''pseudo-action'' * run the script using the ''pseudo-action'' as a parameter * let script know the record types that it will be running on and the way to limit record set for notification rules evaluation. ClearQuest does not have any server based process like cron that can trigger actions. It can be changed in the future (the new ClearQuest Web Server includes request manager that does not have any public interface so far), but as of today, the only way to trigger timed email notification is to run timed notification script from UNIX cron or Windows scheduler on your ClearQuest server. You can download timed notification script [[Download | here]]. == Configuration == For example, we would like to notify assignees about defects that will pass due date in the next 24 hours. I will name pseudo action used in this example '''DailyNotification''' The following tasks need to be accomplished === Configure Scheduler on a ClearQuest server === CQ Web server could be a good candidate to run the script. The following script need to be configured to run daily, let's say at 4 AM <source lang="bash"> cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification" </source> === Enable Notification for the record type === In this example, we need to inform the script that it is running on ''Defect'' record type. In order to do it, '''TN_RecordTypes''' property need to be set to '''Defect''' (udb_property record type has to be submitted with "Defect" value) '''Note''': '''TN_RecordTypes''' property value can contain more then one record type. A list of enabled record types has to be specified as '''one-record-type-per-line'''. === Create email notification rule === Email Notification Rule for Defect record type (major fields) {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Field ! Value |- | Name | Defect_Reminder |- | Record Type | Defect |- | Actions | '''DailyNotification''' |- | Condition | <source lang="perl"> $Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0 </source> |- | To: | <source lang="perl"> ${owner.email} </source> |- | Subject: | <source lang="text">Defect $ID will pass due date $Due_Date soon</source> |- | Body: | <source lang="text">You need to do something with defect $ID</source> |} === Limit record set for notification rules evaluation === It would be too expensive to evaluate the notification rule on each record. It is a good idea to limit an evaluation scope. As it was discussed above, there are 2 ways to do it. ==== Create query in ClearQuest client ==== For example, we can create query that will filter open defect, save as "Public Queries\Admin\DailyNotificationQuery" and set '''TN_Query-Defect-DailyNotification''' property to that value. When script is executed, it checks '''TN_Query-{record type}-{pseudo action name}''' or '''TN_Query-{record type}''' properties if the first one is not defined. '''Note:''' You could have both '''TN_Query-{record type}''' and '''TN_Query-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_Query-{record type}-{pseudo action name}''' would overwrite default value if specified. ==== OR provide filter criteria for dynamic query ==== This way you can specify state names that have to be excluded from the notification. Based on information provided, script will create a query at run time. The states can be specified using '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' or '''TN_QueryExcludeStates-{record type}''' property in one-state-per-line style. In our case, we can submit '''TN_QueryExcludeStates-Defect-DailyNotification''' property with the following values: Submit Closed If 'TN_Query-{record type}-{pseudo action name}' and 'TN_Query-{record type}' properties do not exist, the script checks for excluded state properties and uses them as a filter in run-time created query. '''Note:''' You could have both '''TN_QueryExcludeStates-{record type}''' and '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' would overwrite default value if specified. == Properties used in Timed Notification script == {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Property name ! Description |- | valign="top" | '''''TN_RecordTypes''''' | list of record types enabled for the timed notification script<br /> |- | valign="top" | '''''TN_Query-{record type}-{action name}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for pseudo action {action name} (from the script command line)<br /> Overwrites TN_Query-{record type} property when exists. |- | valign="top" | '''''TN_Query-{record type}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for any pseudo action name |- | valign="top" | '''''TN_QueryExcludeStates-{record type}-{action name}''''' | a set of record states, one per line, that will be filtered out in run-time query for pseudo action {action name}, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist.<br /> Overwrites TN_QueryExcludeStates-{record type} property when exists.<br /> |- | valign="top" | '''''TN_QueryExcludeStates-{record type}''''' | a set of record states, one per line, that will be filtered out in run-time query for any pseudo action, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist. |} <br /> <br /> [[Category:Email_Notification_Package]] 9346b38a52d0ef6759786b55d7a172007b2d0c65 19 18 2010-11-05T00:28:08Z Paul 1 1 revision wikitext text/x-wiki =Timed Notification= == What does Timed Notification mean? == Sometimes we would like to implement notifications that are not triggered by particular action. You might need a reminder that defect approached a resolution deadline, or that a trouble ticket passed due date, was not implemented in time frame required by the Service Level Agreement, was not assigned for implementation in a reasonable time frame. A call such kind of requests Timed Notifications or Reminders. == How Timed Notifications / Reminders are implemented? == There are two parts of the complicated task # find records that are eligible for notification # trigger notifications based on information in selected records === How to find records? === To make it flexible, the selection process is implemented in two phases ==== Initial records selection ==== It is limiting scope based on simple criteria the can be used in a SQL Query to retrieve records. For example, you can limit records based on record type, current state, severity, assignment, etc. Timed Notification script offers you two possibilities: # create a ClearQuest query, and save it in the public workspace # specify criteria to create the query dynamically during the execution ==== Final selection ==== In addition, records can be filtered based on Email Notification Rule ''Condition'' field. It is performed during evaluation of notification rules on the record set selected on the previous step. Rules evaluation is expensive process that is why it very is important to have good initial record selection. === Triggering notifications === Since we are using extremely customizable email notification rules for other actions, it makes sense to use the same functionality, and keep timed notification rules at the same place. Regular notifications are triggered by ''actions'', timed notifications - by ''pseudo-actions''. It means that in reality no action is executed, but the script evaluates email notification rules on selected records in the same way as it would be done if the real action would be invoked. If you noticed, selection of actions on Email Notification Rule record is not limited to actions defined for the record type, and it is done on purpose: you can specify there non-existent, '''pseudo-action''' name. To make all thins working, you just need to * create a notification rule, using ''pseudo-action'' * run the script using the ''pseudo-action'' as a parameter * let script know the record types that it will be running on and the way to limit record set for notification rules evaluation. ClearQuest does not have any server based process like cron that can trigger actions. It can be changed in the future (the new ClearQuest Web Server includes request manager that does not have any public interface so far), but as of today, the only way to trigger timed email notification is to run timed notification script from UNIX cron or Windows scheduler on your ClearQuest server. You can download timed notification script [[Download | here]]. == Configuration == For example, we would like to notify assignees about defects that will pass due date in the next 24 hours. I will name pseudo action used in this example '''DailyNotification''' The following tasks need to be accomplished === Configure Scheduler on a ClearQuest server === CQ Web server could be a good candidate to run the script. The following script need to be configured to run daily, let's say at 4 AM <source lang="bash"> cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification" </source> === Enable Notification for the record type === In this example, we need to inform the script that it is running on ''Defect'' record type. In order to do it, '''TN_RecordTypes''' property need to be set to '''Defect''' (udb_property record type has to be submitted with "Defect" value) '''Note''': '''TN_RecordTypes''' property value can contain more then one record type. A list of enabled record types has to be specified as '''one-record-type-per-line'''. === Create email notification rule === Email Notification Rule for Defect record type (major fields) {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Field ! Value |- | Name | Defect_Reminder |- | Record Type | Defect |- | Actions | '''DailyNotification''' |- | Condition | <source lang="perl"> $Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0 </source> |- | To: | <source lang="perl"> ${owner.email} </source> |- | Subject: | <source lang="text">Defect $ID will pass due date $Due_Date soon</source> |- | Body: | <source lang="text">You need to do something with defect $ID</source> |} === Limit record set for notification rules evaluation === It would be too expensive to evaluate the notification rule on each record. It is a good idea to limit an evaluation scope. As it was discussed above, there are 2 ways to do it. ==== Create query in ClearQuest client ==== For example, we can create query that will filter open defect, save as "Public Queries\Admin\DailyNotificationQuery" and set '''TN_Query-Defect-DailyNotification''' property to that value. When script is executed, it checks '''TN_Query-{record type}-{pseudo action name}''' or '''TN_Query-{record type}''' properties if the first one is not defined. '''Note:''' You could have both '''TN_Query-{record type}''' and '''TN_Query-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_Query-{record type}-{pseudo action name}''' would overwrite default value if specified. ==== OR provide filter criteria for dynamic query ==== This way you can specify state names that have to be excluded from the notification. Based on information provided, script will create a query at run time. The states can be specified using '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' or '''TN_QueryExcludeStates-{record type}''' property in one-state-per-line style. In our case, we can submit '''TN_QueryExcludeStates-Defect-DailyNotification''' property with the following values: Submit Closed If 'TN_Query-{record type}-{pseudo action name}' and 'TN_Query-{record type}' properties do not exist, the script checks for excluded state properties and uses them as a filter in run-time created query. '''Note:''' You could have both '''TN_QueryExcludeStates-{record type}''' and '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' would overwrite default value if specified. == Properties used in Timed Notification script == {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Property name ! Description |- | valign="top" | '''''TN_RecordTypes''''' | list of record types enabled for the timed notification script<br /> |- | valign="top" | '''''TN_Query-{record type}-{action name}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for pseudo action {action name} (from the script command line)<br /> Overwrites TN_Query-{record type} property when exists. |- | valign="top" | '''''TN_Query-{record type}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for any pseudo action name |- | valign="top" | '''''TN_QueryExcludeStates-{record type}-{action name}''''' | a set of record states, one per line, that will be filtered out in run-time query for pseudo action {action name}, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist.<br /> Overwrites TN_QueryExcludeStates-{record type} property when exists.<br /> |- | valign="top" | '''''TN_QueryExcludeStates-{record type}''''' | a set of record states, one per line, that will be filtered out in run-time query for any pseudo action, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist. |} <br /> <br /> [[Category:Email_Notification_Package]] 9346b38a52d0ef6759786b55d7a172007b2d0c65 0 13 24 2008-12-18T10:35:00Z Paul 1 wikitext text/x-wiki = Email Notification Package and ClearQuest 7.1 = <big>'''The package was tested successfully with ClearQuest version 7.1'''</big> == Code Page Enforcement == ClearQuest version 7.1 enforces Code Page settings for packages. If package already applied to your schema, you will see the following "Problem Occurred" message in the new Designer: Show registered packages failed... Failed condition: m_cp != sUnsetCodePage The error message does not tell you names of the failed packages. Please follow the steps below to fix the problem * Add the following line to the '''[General]''' section of "package.ini" files in EmailNotification\1.3 package and UDBProperties\1.1 directories, located in ClearQuest\packages CodePage=1;20127 * After .ini files are updated, re-register packages : (assume ClearQuest 7.1 default location in the example, please update paths when required) packageutil registerpackage EmailNotification 1.3 -unregister packageutil registerpackage EmailNotification 1.2 -unregister packageutil registerpackage EmailNotification 1.1 -unregister packageutil registerpackage EmailNotification 1.0 -unregister packageutil registerpackage UDBProperties 1.1 -unregister packageutil registerpackage UDBProperties 1.0 -unregister packageutil registerpackage UDBProperties 1.1 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\UDBProperties\1.1" packageutil registerpackage EmailNotification 1.3 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\EmailNotification\1.3" The error message will disappear. If you install package in the new schema repository, it will appear in the package list after completing steps above. You need to restart designer, BTW. (Even if you cannot see the package in the list, you can still use packageutil in command line to apply packages) It is not a critical issue, because you need to install packages and perform these steps on machines where you develop your ClearQuest schema only. There is no need to install package on the clients. == Fixed problems == I am glad to announce that the problem with Perl socket library that caused some problems in Eclipse client in 7.0.1 is fixed. The package was successfully tested with all clients, using access and MS SQL Server backend databases and all feature levels. BTW, I would not recommend to deploy 7.1 until first service pack is released, but it is my personal opinion. [[Category:Email_Notification_Package]] c350eaac9aa29fec52f1ca77becf4468e9857481 25 24 2010-11-05T00:28:08Z Paul 1 1 revision wikitext text/x-wiki = Email Notification Package and ClearQuest 7.1 = <big>'''The package was tested successfully with ClearQuest version 7.1'''</big> == Code Page Enforcement == ClearQuest version 7.1 enforces Code Page settings for packages. If package already applied to your schema, you will see the following "Problem Occurred" message in the new Designer: Show registered packages failed... Failed condition: m_cp != sUnsetCodePage The error message does not tell you names of the failed packages. Please follow the steps below to fix the problem * Add the following line to the '''[General]''' section of "package.ini" files in EmailNotification\1.3 package and UDBProperties\1.1 directories, located in ClearQuest\packages CodePage=1;20127 * After .ini files are updated, re-register packages : (assume ClearQuest 7.1 default location in the example, please update paths when required) packageutil registerpackage EmailNotification 1.3 -unregister packageutil registerpackage EmailNotification 1.2 -unregister packageutil registerpackage EmailNotification 1.1 -unregister packageutil registerpackage EmailNotification 1.0 -unregister packageutil registerpackage UDBProperties 1.1 -unregister packageutil registerpackage UDBProperties 1.0 -unregister packageutil registerpackage UDBProperties 1.1 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\UDBProperties\1.1" packageutil registerpackage EmailNotification 1.3 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\EmailNotification\1.3" The error message will disappear. If you install package in the new schema repository, it will appear in the package list after completing steps above. You need to restart designer, BTW. (Even if you cannot see the package in the list, you can still use packageutil in command line to apply packages) It is not a critical issue, because you need to install packages and perform these steps on machines where you develop your ClearQuest schema only. There is no need to install package on the clients. == Fixed problems == I am glad to announce that the problem with Perl socket library that caused some problems in Eclipse client in 7.0.1 is fixed. The package was successfully tested with all clients, using access and MS SQL Server backend databases and all feature levels. BTW, I would not recommend to deploy 7.1 until first service pack is released, but it is my personal opinion. [[Category:Email_Notification_Package]] c350eaac9aa29fec52f1ca77becf4468e9857481 0 7 12 2009-09-24T19:10:09Z Paul 1 wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3, but be careful when placing dot at the end of sentence after a variable - it can trigger an error: "${variable}." is safe, "$variable ." is safe, "$variable." is not) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( (<expression>), <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( ($owner.email ne '' ), $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 43e7dfcaf2327fc5086ed866a084db7ce09a7cdc 13 12 2010-11-05T00:28:07Z Paul 1 1 revision wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3, but be careful when placing dot at the end of sentence after a variable - it can trigger an error: "${variable}." is safe, "$variable ." is safe, "$variable." is not) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( (<expression>), <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( ($owner.email ne '' ), $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 43e7dfcaf2327fc5086ed866a084db7ce09a7cdc 0 5 8 2010-06-16T21:50:59Z James parker 0 Added license section, specifying LGPL; also added "Getting the Software" header to separate downloading paragraph from that section. wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a different SMTP relay. It is not a problem: the package allows you to create goloba as well as site specific settings to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Getting the Software == Would you like to try it? Then, proceed to [[Download | download]] page. Please do not forget to backup your databases and read [[Package_configuration |configuration guide]], before applying changes to your production database. == Examples == Some examples can be found on [[Notification_Examples | Examples]] page. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] cc637c48b2529a33ab169b321fc1699c8a4bc4b9 9 8 2010-11-05T00:28:07Z Paul 1 1 revision wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a different SMTP relay. It is not a problem: the package allows you to create goloba as well as site specific settings to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Getting the Software == Would you like to try it? Then, proceed to [[Download | download]] page. Please do not forget to backup your databases and read [[Package_configuration |configuration guide]], before applying changes to your production database. == Examples == Some examples can be found on [[Notification_Examples | Examples]] page. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] cc637c48b2529a33ab169b321fc1699c8a4bc4b9 0 2 2 2010-11-03T18:34:53Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''This site is under migration''' : The site is moving. I apologize for inconvenience. In interim time, support forum will be available at http://forum.cqadmin.com * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. <br /><br /><br /> [[Category:Rational]] 966b51d0e7399b468e64d68088ce6c0068978ed3 3 2 2010-11-05T00:28:06Z Paul 1 1 revision wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''This site is under migration''' : The site is moving. I apologize for inconvenience. In interim time, support forum will be available at http://forum.cqadmin.com * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. <br /><br /><br /> [[Category:Rational]] 966b51d0e7399b468e64d68088ce6c0068978ed3 44 3 2011-04-24T22:28:37Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. <br /><br /><br /> [[Category:Rational]] 30759da0175a5e8da93ec69fc1a46df3845bc06e 0 14 26 2010-11-05T00:35:48Z Paul 1 Redirected page to [[CQAdmin]] wikitext text/x-wiki #REDIRECT [[CQAdmin]] 24c055c65d39e76d862b255cb6b3946b558d7233 0 15 27 2010-11-05T00:37:00Z Paul 1 Redirected page to [[CQAdmin]] wikitext text/x-wiki #REDIRECT [[CQAdmin]] 24c055c65d39e76d862b255cb6b3946b558d7233 0 16 28 2010-11-05T00:37:43Z Paul 1 Redirected page to [[CQAdmin]] wikitext text/x-wiki #REDIRECT [[CQAdmin]] 24c055c65d39e76d862b255cb6b3946b558d7233 8 17 29 2010-11-05T00:41:53Z Paul 1 Created page with "* navigation ** mainpage|CQ Admin Home ** ClearQuest_Email_Notification_Package | Email notification package ** Download | Downloads ** http://forum.cqadmin.org | Forum ** Catego..." wikitext text/x-wiki * navigation ** mainpage|CQ Admin Home ** ClearQuest_Email_Notification_Package | Email notification package ** Download | Downloads ** http://forum.cqadmin.org | Forum ** Category:Email_Notification_Package | Index * SEARCH * TOOLBOX * LANGUAGES f4449f3f03ce4bc089db63c32d8dfea194e3f548 6 18 30 2010-11-05T00:43:55Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 19 31 2010-11-05T00:44:14Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 20 32 2010-11-05T00:44:30Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 21 33 2010-11-05T00:44:49Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 22 34 2010-11-05T00:45:09Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 23 35 2010-11-05T00:45:26Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 24 36 2010-11-05T00:45:42Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 25 37 2010-11-05T00:46:03Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 26 38 2010-11-05T00:46:30Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 27 39 2010-11-05T00:46:53Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 28 40 2010-11-05T00:47:13Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 29 41 2010-11-05T00:47:30Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 30 42 2010-11-05T00:47:47Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 14 31 43 2010-11-05T00:50:21Z Paul 1 Created page with "IBM-Rational Tools" wikitext text/x-wiki IBM-Rational Tools 4d377cff4ec4b8d8d2c72fddb58a72549bf7f825 0 32 45 2011-08-19T15:19:42Z Paul 1 Created page with "<big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQue..." wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. == Configuration == == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 055db3dba8eff5f70328bcb8e55c738066a550f8 0 33 46 2011-08-19T19:15:41Z Paul 1 Created page with "<big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows t..." wikitext text/x-wiki <big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == == Queue Delivery == == Other Considerations == == Custom Delivery Mechanisms == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] ab0d0477a3fcb69c20c09e0f49c1b1abfd918f7f 49 46 2011-08-19T19:31:16Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.jpg | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database to be queried (2) and delivered (3) by the same or other client later. == Queue Delivery == == Other Considerations == == Custom Delivery Mechanisms == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] fd4602aeb21c519e771b62a316541127796b5461 51 49 2011-08-19T19:32:41Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == == Other Considerations == == Custom Delivery Mechanisms == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] fda7aef6d8719fb1a2b02a04e50e55c9aa730711 6 34 47 2011-08-19T19:16:12Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 35 48 2011-08-19T19:16:30Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 36 50 2011-08-19T19:31:51Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 37 52 2011-08-19T19:47:26Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 33 53 51 2011-08-19T20:09:14Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == Another common way to process notifications is '''Queue''' delivery mode. [[File:Queue_Delivery.png | center]] In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by [http://cqadmin.org/wiki/Download delivery script] (2) running on the ClearQuest server(s). We usually use ClearQuest Web (CM) server for scheduled execution of the script. Queue delivery might be extremely useful when sending emails from users' desktops is restricted by organization policy, blocked by security software, firewall, or fails due to application bugs (for example, in some versions ClearQuest 7.0 Eclipse client). It also improve end-user performance, in comparison with Deferred mode, as actions are not delayed while sending emails. == Other Considerations == Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely message delivery even with no user activity. Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to periodically purge the table. == Custom Delivery Mechanisms == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] a7b7c00bd5ee010decb91f886c40d10f5a988fbc 55 53 2011-08-19T20:35:56Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> Delivery Mode The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == Another common way to process notifications is '''Queue''' delivery mode. [[File:Queue_Delivery.png | center]] In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by [http://cqadmin.org/wiki/Download delivery script] (2) running on the ClearQuest server(s). The only requirement for the server is to have ClearQuest installed and database connection configured. ClearQuest Web (CM) servers could be good candidates for scheduled execution of the script, and it might make sense to configure more than one for redundancy. Queue delivery might be extremely useful when sending emails from users' desktops is restricted by organization policy, blocked by security software, firewall, or fails due to application bugs (for example, in some versions ClearQuest 7.0 Eclipse client). It also improve end-user performance, in comparison with Deferred mode, as actions are not delayed while sending emails. == Other Considerations == Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely message delivery even with no user activity. Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to periodically purge the table. A simple script can be found on [http://cqadmin.org/wiki/Download Downloads] page. == Custom Delivery Mechanisms == SMTP along with offered delivery modes should be able to satisfy most of the requirements. Nevertheless, it might be required to employ custom delivery mechanism. Fortunately, Queue delivery mode opens this possibility. When Queue mode is used, Email Notification package would ensure that all generated messages are stored in the database, and you can implement desirable delivery protocol by taking simple delivery script as an example. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 18f6648a974151c75223dc98997348fe372d27e3 56 55 2011-08-19T20:36:17Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == Another common way to process notifications is '''Queue''' delivery mode. [[File:Queue_Delivery.png | center]] In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by [http://cqadmin.org/wiki/Download delivery script] (2) running on the ClearQuest server(s). The only requirement for the server is to have ClearQuest installed and database connection configured. ClearQuest Web (CM) servers could be good candidates for scheduled execution of the script, and it might make sense to configure more than one for redundancy. Queue delivery might be extremely useful when sending emails from users' desktops is restricted by organization policy, blocked by security software, firewall, or fails due to application bugs (for example, in some versions ClearQuest 7.0 Eclipse client). It also improve end-user performance, in comparison with Deferred mode, as actions are not delayed while sending emails. == Other Considerations == Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely message delivery even with no user activity. Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to periodically purge the table. A simple script can be found on [http://cqadmin.org/wiki/Download Downloads] page. == Custom Delivery Mechanisms == SMTP along with offered delivery modes should be able to satisfy most of the requirements. Nevertheless, it might be required to employ custom delivery mechanism. Fortunately, Queue delivery mode opens this possibility. When Queue mode is used, Email Notification package would ensure that all generated messages are stored in the database, and you can implement desirable delivery protocol by taking simple delivery script as an example. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 8a1db43458037050ae27d02b00f745a602feff6e 57 56 2011-08-19T20:47:03Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> The package was designed to use Simple Mail Transfer Protocol (SMTP) to deliver generated notification messages. SMTP allows to unify configuration for all ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be the first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in as well. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package performs delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All notifications created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when other action is performed later by the same or other ClearQuest client, at the end of rules evaluation cycle (4) and delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with the database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the messages will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == Another common way to process notifications is '''Queue''' delivery mode. [[File:Queue_Delivery.png | center]] In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by [http://cqadmin.org/wiki/Download delivery script] (2) running on the ClearQuest server(s). The only requirement for the server is to have ClearQuest installed and database connection configured. ClearQuest Web (CM) servers could be good candidates for scheduled execution of the script, and it might make sense to configure more than one for redundancy. Queue delivery might be extremely useful when sending emails from users' desktops is restricted by security policy, blocked by firewall, or fails due to application bugs (for example, socket library in some versions ClearQuest 7.0 Eclipse client). It also improves end-user performance, in comparison with Deferred mode, as actions are not delayed for sending emails. == Other Considerations == Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely delivery of email even with no user activity on the database. Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to purge the table periodically. A simple script can be found on [http://cqadmin.org/wiki/Download Downloads] page. == Custom Delivery Mechanisms == SMTP along with offered delivery modes should satisfy most of the users' requirements, but sometimes, it might be required to employ custom delivery mechanisms. Fortunately, Queue delivery mode opens this possibility. When Queue mode is used, Email Notification package would ensure that all generated messages are stored in the database, and you can implement desirable delivery protocol by taking simple delivery script as an example and enhancing it. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] fcc94026ae193bf7fbe9094c53f57cb5fa6f25d1 0 6 54 11 2011-08-19T20:11:47Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === Click [http://cqadmin.org/data/EmailNotification_Package.zip here] to download the latest version of the package. === Delivery Script === [http://cqadmin.org/data/EmailNotification_DeliveryScript.zip Simple delivery script] is required for queue delivery mode, so download is optional. === Purge Message Queue === [http://cqadmin.org/data/purge_message_queue.zip Purge message script] could be used to delete unnecessary messages from the queue. You can implement scheduled execution to run it periodically. === Timed Notification Script === [http://cqadmin.org/data/TimedNotification.zip Timed notification script] is also optional. Please refer to [[Timed_Notification | Timed Notification]] page for more information. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 2908cf6f364607f9ede69390f2727ea364c5a0f1 80 54 2011-08-30T19:43:17Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === Click [http://cqadmin.org/data/EmailNotification_Package.zip here] to download the latest version of the package. <br />(previous versions are available [http://cqadmin.org/data/EmailNotification_Package.13.zip here]) === Delivery Script === [http://cqadmin.org/data/EmailNotification_DeliveryScript.zip Simple delivery script] is required for queue delivery mode, so download is optional. === Purge Message Queue === [http://cqadmin.org/data/purge_message_queue.zip Purge message script] could be used to delete unnecessary messages from the queue. You can implement scheduled execution to run it periodically. === Timed Notification Script === [http://cqadmin.org/data/TimedNotification.zip Timed notification script] is also optional. Please refer to [[Timed_Notification | Timed Notification]] page for more information. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] a5f030bc2a94edab082f19fe6e43bb77320fc520 0 32 58 45 2011-08-21T19:44:00Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is not available in wizard. You would need to use command line. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] d6989037c6aa94dba303fac2e3875df34432bb56 62 58 2011-08-22T14:44:08Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is not available in wizard. You would need to use command line. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 9f2ce3c31344e7117f61887c9fb953d42225d74a 0 12 59 23 2011-08-21T20:10:27Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> lets define two functions in database properties:<br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Sending HTML Emails == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} <br /><br /> [[Category:Email_Notification_Package]] 79b8943f3835ecaf93aec6cccf5e949e0dc8c498 60 59 2011-08-22T01:52:03Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Sending HTML Emails == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} == Sending Emails with Attachments == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } return $result; # TRUE if current record has attachment</source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> [[Category:Email_Notification_Package]] 35640dcf507e72aa349cf35a58aa619755604331 0 5 61 9 2011-08-22T13:51:48Z Paul 1 /* Site-specific settings in Multisited environment */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Getting the Software == Would you like to try it? Then, proceed to [[Download | download]] page. Please do not forget to backup your databases and read [[Package_configuration |configuration guide]], before applying changes to your production database. == Examples == Some examples can be found on [[Notification_Examples | Examples]] page. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] c2c746cc0062b4fd85a36b7155d20feff7723467 67 61 2011-08-22T20:51:00Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] # Enjoy! == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]]. # [[ClearQuest_Email_Notification_Package_FAQ | and Frequently Asked Questions ]] # Please check some [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 6c7877435e93cbf76f13f3674dc3e777ff668f7e 68 67 2011-08-22T20:51:50Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] # Enjoy! == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]]. # [[ClearQuest_Email_Notification_Package_FAQ | and Frequently Asked Questions ]] # Please check some [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 9ce56d0cf1dcc3ad349bb416d74c297a3d492a5c 69 68 2011-08-22T20:52:13Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] # Enjoy! == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]]. # [[ClearQuest_Email_Notification_Package_FAQ | and Frequently Asked Questions ]] # Please check some [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] bc4b4fee5e3757fe867e640346b9aeac97ef354c 94 69 2011-08-31T16:23:13Z Paul 1 /* Additional Information */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is better. Click [[ClearQuest_Email_Notification_Package_Reasons | here]] if you would like to know why it was created. The package was presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] I would better give you a quick overview some of the advantages. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but not sent to users. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It is nice that you have a option to configure it in email notification rule. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, or you can select a dedicated email address that will be used for all emails generated in the database. It might make it more convenient for users to configure their email filters. In addition, it can help you to satisfy mail relaying policies in very restrictive environments. You can configure different email, Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] # Enjoy! == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] f82ae802a1a926637825da97ba70429b11335589 96 94 2011-09-01T02:42:00Z Paul 1 /* Email Notification Package */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It a replacement for existing package that allows you to overcome drawbacks of standard solution and satisfy all possible requirements that you might have, creating your own custom emails using plain text or HTML format. The main goal was to allow as much customization as possible without modifying ClearQuest schema. You need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] # Enjoy! == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 5023e7b8dc71d8e5809a33d612d604014d7bcbd8 97 96 2011-09-01T02:42:45Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It a replacement for existing package that allows you to overcome drawbacks of standard solution and satisfy all possible requirements that you might have, creating your own custom emails using plain text or HTML format. The main goal was to allow as much customization as possible without modifying ClearQuest schema. You need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3cdf2b333c0be3aa5373cbdf5a27fcbf8e36678c 98 97 2011-09-01T02:47:36Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It a replacement for existing package that allows you to overcome drawbacks of standard solution and satisfy all possible requirements that you might have, creating your own custom emails using plain text or HTML. The package offers ultimately flexible way of customizing notifications with no modifications of ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 2a4361df05155d89ee27cfb46b1c5e3857759dc0 99 98 2011-09-01T02:50:17Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It a replacement for existing package that allows you to overcome drawbacks of standard solution and satisfy all possible requirements that you might have, creating your own custom emails using plain text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 4525cf442a14a613fefbdbdc5a63bed85a6ad0e3 100 99 2011-09-01T02:51:47Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all possible requirements that you might have, creating your own custom emails using plain text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 44aec6f54840c8e0c8ada7755f05d2346c77ade2 101 100 2011-09-01T02:52:58Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 40446bbab37adc3afb7eb911a90d783f1f9b1aa7 0 10 63 19 2011-08-22T18:54:22Z Paul 1 wikitext text/x-wiki =Timed Notification= == What does Timed Notification mean? == Sometimes we would like to implement notifications that are not triggered by particular action. You might need a reminder that defect approached a resolution deadline, or that a trouble ticket passed due date, was not implemented in time frame required by the Service Level Agreement, was not assigned for implementation in a reasonable time frame. I call such kind of requests Timed Notifications or Reminders. == How Timed Notifications / Reminders are implemented? == There are two parts of the complicated task # find records that could be eligible for notification # trigger notifications based on information in selected records === How to find records? === To make it flexible and to avoid waste of resources, the selection process is implemented in two phases: # '''Initial records selection''' selects records that might be eligible, define notification scope. #: It would be too expensive to check evaluate every ClearQuest record to determine whether or not notification condition met. In order to improve performance and reduce load on the database, we need to reduce number or records for evaluation. For example, when implementing due date reminder, we could safely exclude closed or resolved defects. It could be different in other cases, but the main goal would always be defining potential notification scope, then # '''Final selection''' evaluates notification rules on selected at step (1) records and triggers notification if condition is met (for example, the record passed due date). ==== Initial records selection ==== It is limiting scope based on simple criteria that can be used in a SQL Query to retrieve records. For example, you can limit records based on record type, current state, severity, assignment, etc. Timed Notification script offers you two possibilities: # create a ClearQuest query, and save it in the public workspace # specify criteria to create the query dynamically during the execution ==== Final selection ==== In addition, records can be filtered based on Email Notification Rule ''Condition'' field. It is performed during evaluation of notification rules on the record set selected on the previous step. Rules evaluation is expensive process that is why it very is important to have good initial record selection. === Triggering notifications === Since we are using extremely customizable email notification rules for other actions, it makes sense to use the same functionality, and keep timed notification rules at the same place. Regular notifications are triggered by ''actions'', timed notifications - by ''pseudo-actions''. It means that in reality no action is executed, but the script evaluates email notification rules on selected records in the same way as it would be done if the real action would be invoked. If you noticed, selection of actions on Email Notification Rule record is not limited to actions defined for the record type, and it is done on purpose: you can specify there non-existent, '''pseudo-action''' name. To make all thins working, you just need to * create a notification rule, using ''pseudo-action'' * run the script using the ''pseudo-action'' as a parameter * let script know the record types that it will be running on and the way to limit record set for notification rules evaluation. ClearQuest does not have any server based process like cron that can trigger actions. It can be changed in the future (the new ClearQuest Web Server includes request manager that does not have any public interface so far), but as of today, the only way to trigger timed email notification is to run timed notification script from UNIX cron or Windows scheduler on your ClearQuest server. You can download timed notification script [[Download | here]]. == Configuration == For example, we would like to notify assignees about defects that will pass due date in the next 24 hours. I will name pseudo action used in this example '''DailyNotification''' The following tasks need to be accomplished === Configure Scheduler on a ClearQuest server === CQ Web server could be a good candidate to run the script. The following script need to be configured to run daily, let's say at 4 AM <source lang="bash"> cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification" </source> === Enable Notification for the record type === In this example, we need to inform the script that it is running on ''Defect'' record type. In order to do it, '''TN_RecordTypes''' property need to be set to '''Defect''' (udb_property record type has to be submitted with "Defect" value) '''Note''': '''TN_RecordTypes''' property value can contain more then one record type. A list of enabled record types has to be specified as '''one-record-type-per-line'''. === Create email notification rule === Email Notification Rule for Defect record type (major fields) {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Field ! Value |- | Name | Defect_Reminder |- | Record Type | Defect |- | Actions | '''DailyNotification''' |- | Condition | <source lang="perl"> $Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0 </source> |- | To: | <source lang="perl"> ${owner.email} </source> |- | Subject: | <source lang="text">Defect $ID will pass due date $Due_Date soon</source> |- | Body: | <source lang="text">You need to do something with defect $ID</source> |} === Limit record set for notification rules evaluation === It would be too expensive to evaluate the notification rule on each record. It is a good idea to limit an evaluation scope. As it was discussed above, there are 2 ways to do it. ==== Create query in ClearQuest client ==== For example, we can create query that will filter open defect, save as "Public Queries\Admin\DailyNotificationQuery" and set '''TN_Query-Defect-DailyNotification''' property to that value. When script is executed, it checks '''TN_Query-{record type}-{pseudo action name}''' or '''TN_Query-{record type}''' properties if the first one is not defined. '''Note:''' You could have both '''TN_Query-{record type}''' and '''TN_Query-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_Query-{record type}-{pseudo action name}''' would overwrite default value if specified. ==== OR provide filter criteria for dynamic query ==== This way you can specify state names that have to be excluded from the notification. Based on information provided, script will create a query at run time. The states can be specified using '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' or '''TN_QueryExcludeStates-{record type}''' property in one-state-per-line style. In our case, we can submit '''TN_QueryExcludeStates-Defect-DailyNotification''' property with the following values: Submit Closed If 'TN_Query-{record type}-{pseudo action name}' and 'TN_Query-{record type}' properties do not exist, the script checks for excluded state properties and uses them as a filter in run-time created query. '''Note:''' You could have both '''TN_QueryExcludeStates-{record type}''' and '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' would overwrite default value if specified. == Properties used in Timed Notification script == {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Property name ! Description |- | valign="top" | '''''TN_RecordTypes''''' | list of record types enabled for the timed notification script<br /> |- | valign="top" | '''''TN_Query-{record type}-{action name}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for pseudo action {action name} (from the script command line)<br /> Overwrites TN_Query-{record type} property when exists. |- | valign="top" | '''''TN_Query-{record type}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for any pseudo action name |- | valign="top" | '''''TN_QueryExcludeStates-{record type}-{action name}''''' | a set of record states, one per line, that will be filtered out in run-time query for pseudo action {action name}, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist.<br /> Overwrites TN_QueryExcludeStates-{record type} property when exists.<br /> |- | valign="top" | '''''TN_QueryExcludeStates-{record type}''''' | a set of record states, one per line, that will be filtered out in run-time query for any pseudo action, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist. |} <br /> <br /> [[Category:Email_Notification_Package]] 0958bf85ddc4e57c424a63e8319e442908ada851 0 8 64 15 2011-08-22T19:06:59Z Paul 1 /* Create simple notification rule */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you created backup to be able to roll back the change if necessary. == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.3 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] Please also check [[Applying_Package_to_Stateless_Records| applying package to a stateless record type]] section. == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Open ClearQuest and configure package according to package configuration instructions == submit properties: [[Image:submit_properties.jpg | none ]] === Set mail_host = your SMTP host === [[Image:email_host.jpg]] === Set email_enabled = 1 === Second mandatory property besides mail_host. Notifications will not be generated is the property is not set! === Set other properties if required === Check other available properties in the [[Package_configuration | configuration guide]] === Create simple notification rule === [[Image:submit_Email_Notification_Rule.jpg]] For example, a simple rule to notify submitter that Defect is closed: [[Image:en_1.jpg]] [[Image:en_2.jpg]] [[Image:en_3.jpg]] === Test created notification rule === [[Category:Email_Notification_Package]] 852d5ee32d1e0244af18dfd822c6c94e39512065 66 64 2011-08-22T19:45:29Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you '''created backup''' to be able to roll back the change if necessary. It is strongly recommended to test it on a test copy of your schema first. Also, it would make sense to use it with the same database vendor as your production database. In this case, you can minimize risks and safely deploy the package to your production schema and database later. Are you scared yet? == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.3 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] Please also check [[Applying_Package_to_Stateless_Records| applying package to a stateless record type]] section. == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Configuring Package == Proceed to [[EmailNotification_Creating_First_Notification_Rule | Creating First Notification Rule]] section. [[Category:Email_Notification_Package]] 2c6c4b64faf2bac83be4356cef8f51e87d258722 0 38 65 2011-08-22T19:39:07Z Paul 1 Created page with "<big>'''ClearQuest Email Notification Package'''</big> <big>'''Creating first notification rule'''</big> == Minimum configuration == Detailed package configuration instructio..." wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <big>'''Creating first notification rule'''</big> == Minimum configuration == Detailed package configuration instructions can be found [[Package_configuration | here]] At least two database propertied must be defined to start using the package: # '''email_host''' - SMTP relay name, the host that will accept generated emails for delivery # '''email_enabled''' - should be set to 1 to enable email notifications Open ClearQuest and configure package according to package configuration instructions submit properties (udb_property records): [[Image:submit_properties.jpg | none ]] === Set mail_host = your SMTP host === [[Image:email_host.jpg]] === Set email_enabled = 1 === Second mandatory property besides mail_host. Notifications will not be generated is the property is not set! Submit udb_property record, set name to '''email_enabled''' and value '''1''', click OK to commit property to the database. === Set other properties if required === Check other available properties in the [[Package_configuration | configuration guide]] === Create simple notification rule === In this example, we will define a rule to notify submitted that defect is closed. We are using standard Defect record from "Defect Tracking" schema. [[Image:submit_Email_Notification_Rule.jpg]] Create new email_notification_rule record [[Image:en_1.jpg]] Set name to some unique value, "Notify Submitter", and record type field to "Defect" (the package must be applied for this record type). Action "Close" will trigger notification, because we specified it in the "Actions" field. [[Image:en_2.jpg]] The email is going to be sent to submitter, and we use "$Submitter.email" variable (extracting email from Submitter ClearQuest reference field). We can also add some statics email addresses here as free text, one email address per line, not other delimiters, i.e. $owner.email my_favorite_email_address@my.domain.com [[Image:en_3.jpg]] We are using free text with embedded ClearQuest record fields to format email body. === Test created notification rule === Close a defect, and check if email was created and sent properly. You can use existing or create new query for en_email_message record type to check email queue, [[Category:Email_Notification_Package]] 0ef77484827ecb2dad82d81280ead52307d98ffb 0 2 70 44 2011-08-22T21:33:17Z Paul 1 /* Resources */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML email, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 4899770b3f4777cb1dd7ae93a158b872f6bec576 71 70 2011-08-22T21:34:18Z Paul 1 /* Resources */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich fonts and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 381dfd0b19273b23f4bbb1dd22bf8451a8f0d55c 72 71 2011-08-22T21:34:42Z Paul 1 /* Resources */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] ec7b2cc00883513f88150656c9fe5d8109507c16 78 72 2011-08-30T19:36:11Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.4 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, and end-users self-subscription with optional EmailSubscription package. Please check [[Email_Notification_1.4_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] e3a6c59e5d74e6aa50c46a733c39c586da721dd7 79 78 2011-08-30T19:37:19Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.4 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.4_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 19cda4aa0aeb0c2e600e2f47d89fed8b63fbf415 0 39 73 2011-08-30T02:49:09Z Paul 1 Created page with "<big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing ad..." wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === Dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Parser === ==== Expressions in function list of parameters ==== In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> ==== $EmailNotificationRuleName built-in variable ==== New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="80%" align="left" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |- |} == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 0ab28960536167629016c23d955e2555432b9dcd 74 73 2011-08-30T03:03:47Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === Dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Parser === ==== Expressions in function list of parameters ==== In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> ==== $EmailNotificationRuleName built-in variable ==== New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="left" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <p> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 7ee77f84ae91b758e551bc9dfbe6c3febaac15c1 75 74 2011-08-30T03:04:59Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Parser === ==== Expressions in function list of parameters ==== In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> ==== $EmailNotificationRuleName built-in variable ==== New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="left" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <p> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 6cf4c104c2e582bb3a09d9b4f67a36a192f8d8b4 76 75 2011-08-30T03:06:07Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="left" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <p> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 29902357850ad774c38adb34a5aed248218b89fd 77 76 2011-08-30T12:30:54Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 6e5a47354a79031b2c025eef5d34311409576503 81 77 2011-08-31T02:08:09Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] a18578acb899db6c3aca1dfc40d7a1ac0aa67c19 82 81 2011-08-31T02:08:32Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3ffb0ec1cb2b071d68f9b4f683bbbf2c50886635 0 7 83 13 2011-08-31T15:33:08Z Paul 1 wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3, but be careful when placing dot at the end of sentence after a variable - it can trigger an error: "${variable}." is safe, "$variable ." is safe, "$variable." is not) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] a6874ef69842a60e8a52fea34e9017a838e19b77 84 83 2011-08-31T15:34:36Z Paul 1 /* Variable Syntax */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 974d0c8a59a7f221868dc866771bc10bdfbad323 85 84 2011-08-31T15:42:19Z Paul 1 /* Notification Rules */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 880f9a5e0a22ca0a99874713bb136d553e595a50 86 85 2011-08-31T15:43:23Z Paul 1 /* Notification Rules */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 33ad8670577e6a207a9e3349ec52eab279f4f851 87 86 2011-08-31T15:43:50Z Paul 1 /* Notification Rules */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of property "Property_Name" |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 8cd1b3c4728c4fed453b356ac5bb28af0101138d 88 87 2011-08-31T15:45:22Z Paul 1 /* Examples: */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] e77a08a0a85ac1e74e510417f754b6027450d6b9 89 88 2011-08-31T16:06:16Z Paul 1 /* Notification Rules */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expression in round brackets ( ) * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] f2a7693bb82acfa4a37ae46e7abc32f1387ae8fd 90 89 2011-08-31T16:07:08Z Paul 1 /* Functions */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF(($attempt > 0), 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 2444a56186506d343e45bbece7e61f4342a8f3c3 91 90 2011-08-31T16:07:38Z Paul 1 /* Function name lookup order */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. '''Note:''' due to a bug in CQ 2002 (if somebody still use it), all users must have 'SQL Editor' rights on that platform. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] c30ff308467185bedd2aaa1545bdb5a8339daa9b 92 91 2011-08-31T16:11:25Z Paul 1 /* Installation */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. <br /> EmailSubscription is an optional package delivering end-user self-subscription functionality. '''Note:''' Staring 1.4 release, the package can be installed on ClearQuest 7.0 Designer machine, but still can be used with older clients, if necessary. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] ffe3c97e9692a379f2ffc6090dbffda9403c20a8 93 92 2011-08-31T16:21:06Z Paul 1 wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. <br /> EmailSubscription is an optional package delivering end-user self-subscription functionality. '''Note:''' Staring 1.4 release, the package can be installed on ClearQuest 7.0 Designer machine, but still can be used with older clients, if necessary. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Access control = '''udb_property''' and '''Email_Notification_Rule''' records are protected using security context (udb_visibility). By default, security context field is not set, and superuser only can submit, update, or delete configuration records. You can delegate maintenance tasks by creating desirable security context records and setting PropertyDefaultSecurityGroup and NotificationDefaultSecurityGroup database properties to populate security context field automatically when records are created (records existing before setting these properties would need to be updated manually). Default security group properties also affect action permissions. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 86435e15f0bef3e6066de4a781571e3c42c3d9ae 6 40 95 2011-09-01T02:26:52Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 32 102 62 2011-09-01T02:54:01Z Paul 1 /* Can I apply package to a stateless record type? */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] dd0a849af71cd2bfc7412a06fbb4e88286180ffb 103 102 2011-09-01T03:12:36Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 7c694f9e1f5eda378b3c38493c47964b7773d594 104 103 2011-09-01T03:13:08Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 55b04da40967f38bde5299525a86ea231e671dbe 106 104 2011-09-01T03:59:04Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I call one User Defined function from another? === Yes, you can use '''EN_CALL_UDF''' function and supply other function name and parameters, but it is not the only way to reuse functionality. You can also define "common block" in a database property and "include" it in other user defined functions. For example, you can defined property that contains common function definitions {| border="1" width="60%" ! width="40%" | Property Name ! Value |- | MY_COMMON_BLOCK | <source lang="perl">sub func1 { ... } sub func2 { ... } sub func3 { ... } </source> |} and then re-use it in other user-defined functions {| border="1" width="60%" ! width="40%" |Property Name ! Value |- | MY_FUNCTION | <source lang="perl"> eval GetProperty('MY_COMMON_BLOCK'); ... </source> |} === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 68b24f31231c83340428a9d613c6e133cabb775b 121 106 2011-11-15T20:18:17Z Paul 1 /* What version of ClearQuest the package Can be used with? */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] EmailNotification 1.5 can be installed using ClearQuest Designer 7.0 or later. No additional modifications are required. === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I call one User Defined function from another? === Yes, you can use '''EN_CALL_UDF''' function and supply other function name and parameters, but it is not the only way to reuse functionality. You can also define "common block" in a database property and "include" it in other user defined functions. For example, you can defined property that contains common function definitions {| border="1" width="60%" ! width="40%" | Property Name ! Value |- | MY_COMMON_BLOCK | <source lang="perl">sub func1 { ... } sub func2 { ... } sub func3 { ... } </source> |} and then re-use it in other user-defined functions {| border="1" width="60%" ! width="40%" |Property Name ! Value |- | MY_FUNCTION | <source lang="perl"> eval GetProperty('MY_COMMON_BLOCK'); ... </source> |} === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 9153e8f25b6c9a107f650b69e3541f9bc3ebebdf 122 121 2011-11-15T20:18:31Z Paul 1 /* What version of ClearQuest the package Can be used with? */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] EmailNotification 1.5 can be installed using ClearQuest Designer 7.0 or later. No additional modifications are required. === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I call one User Defined function from another? === Yes, you can use '''EN_CALL_UDF''' function and supply other function name and parameters, but it is not the only way to reuse functionality. You can also define "common block" in a database property and "include" it in other user defined functions. For example, you can defined property that contains common function definitions {| border="1" width="60%" ! width="40%" | Property Name ! Value |- | MY_COMMON_BLOCK | <source lang="perl">sub func1 { ... } sub func2 { ... } sub func3 { ... } </source> |} and then re-use it in other user-defined functions {| border="1" width="60%" ! width="40%" |Property Name ! Value |- | MY_FUNCTION | <source lang="perl"> eval GetProperty('MY_COMMON_BLOCK'); ... </source> |} === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 8129cd52b0f4c9877650b4ac54608dae943effd1 123 122 2011-11-16T13:19:34Z Paul 1 /* What version of ClearQuest the package Can be used with? */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === EmailNotification 1.5 can be installed using ClearQuest Designer 7.0 or later. No additional modifications are required. For older versions of the package, ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I call one User Defined function from another? === Yes, you can use '''EN_CALL_UDF''' function and supply other function name and parameters, but it is not the only way to reuse functionality. You can also define "common block" in a database property and "include" it in other user defined functions. For example, you can defined property that contains common function definitions {| border="1" width="60%" ! width="40%" | Property Name ! Value |- | MY_COMMON_BLOCK | <source lang="perl">sub func1 { ... } sub func2 { ... } sub func3 { ... } </source> |} and then re-use it in other user-defined functions {| border="1" width="60%" ! width="40%" |Property Name ! Value |- | MY_FUNCTION | <source lang="perl"> eval GetProperty('MY_COMMON_BLOCK'); ... </source> |} === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:ClearQuest]] [[Category:Email_Notification_Package]] b6654e410f8c70ebabdf180a1008498a770eb243 0 39 105 82 2011-09-01T03:36:41Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Requirements == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be used with older clients as well. == Read More == * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 1cec4b042162fe8850b1a8e7079222ea598045a3 107 105 2011-09-01T13:20:54Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Prerequisites == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be '''used''' with older clients as well. == Read More == * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] a0880592debf86b9824061678d254c4723de6273 108 107 2011-09-01T13:21:42Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Prerequisites == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be '''used''' with pre-7.0 clients as well. == Read More == * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 9c944aa1be136aefb6b01122b46edac9b7425c0a 0 41 109 2011-09-04T11:49:07Z Paul 1 Created page with "<big>'''ClearQuest Email Subscription'''</big> You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with option..." wikitext text/x-wiki <big>'''ClearQuest Email Subscription'''</big> You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional EmailSubscription package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. For example, you have constant request from users to be notified about new defects. In order to avoid excessive administrative task, you can open Email Notification rule for self-subscription. === Email Notification Rule === In our example, Email notification rule record would trigger a notification when new defect is created, by "Submit" action. We can either leave recipients list empty, or specify emails where the notification would be sent regardless of subscription. === Create Email Subscription Record === When Email Notification Rule exists, it can be opened for end-users self-subscription by creating Email Subscription record. You can give the record descriptive name, for example, "New Defects Subscription" and specify email notification rule. When record is committed, '''ES_GetSubscribersEmails()''' function will be added in the '''To:''' field of Email Notification Rule. You can update Email Notification Rule to move ES_GetSubscribersEmails() to CC or BCC fields if necessary. End users can manage their subscription by using '''Subscribe_Me''' or '''Unsubscribe_Me''' actions on the correspondent Email_Subscription record. More than one Notification Rule can be associated with Email Subscription record. In multisited environment, Email Subscription record needs to be created for each site where subscription is enabled: end users would be able to update subscription records that are mastered on their local site only. [[ClearQuest_Email_Notification_Package | Back to the package page]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] aafbc902b4e330dde4317baa290e17172e773995 129 109 2012-05-17T14:19:19Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Subscription'''</big> You can allow users to manage their email notification rules subscription preferences. This functionality is delivered with optional EmailSubscription package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. For example, you have constant request from users to be notified about new defects. In order to avoid excessive administrative task, you can open Email Notification rule for self-subscription. === Email Notification Rule === In our example, Email notification rule record would trigger a notification when new defect is created, by "Submit" action. We can either leave recipients list empty, or specify emails where the notification would be sent regardless of subscription. === Create Email Subscription Record === When Email Notification Rule exists, it can be opened for end-users self-subscription by creating Email Subscription record. You can give the record descriptive name, for example, "New Defects Subscription" and specify email notification rule. When record is committed, '''ES_GetSubscribersEmails()''' function will be added in the '''To:''' field of Email Notification Rule. You can update Email Notification Rule to move ES_GetSubscribersEmails() to CC or BCC fields if necessary. End users can manage their subscription by using '''Subscribe_Me''' or '''Unsubscribe_Me''' actions on the correspondent Email_Subscription record. More than one Notification Rule can be associated with Email Subscription record. In multisited environment, Email Subscription record needs to be created for each site where subscription is enabled: end users would be able to update subscription records that are mastered on their local site only. [[ClearQuest_Email_Notification_Package | Back to the package page]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 09288d4106ecd0ec03341111aec2e9fcbeff9fe4 0 5 110 101 2011-09-04T11:54:25Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notification]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 2145b3fd9e4b9945b1c766301d68fe203ba54ec0 113 110 2011-09-04T13:10:37Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 2d1f5be2fca6e9b0ab08a65c70ec0e52c54bd109 127 113 2011-12-15T21:38:45Z Paul 1 /* Email Notification Package */ wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 752af73b85c65e4c25d41ba93e48344e166cab4a 132 127 2012-05-17T18:37:00Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Support == : ClearQuest Email Notification package is [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html officially supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 4832ae5b46bcb970ea6e1f59127a88a0895fcdea 0 13 111 25 2011-09-04T13:09:17Z Paul 1 wikitext text/x-wiki = Email Notification Package and ClearQuest 7.1 = <big>'''The package was tested successfully with ClearQuest version 7.1'''</big> == Code Page Enforcement == <big><font color = "red">'''The following steps were necessary for pre-1.4 releases only and no longer required!'''</font></big> <small><small>ClearQuest version 7.1 enforces Code Page settings for packages. If package already applied to your schema, you will see the following "Problem Occurred" message in the new Designer: Show registered packages failed... Failed condition: m_cp != sUnsetCodePage The error message does not tell you names of the failed packages. Please follow the steps below to fix the problem * Add the following line to the '''[General]''' section of "package.ini" files in EmailNotification\1.3 package and UDBProperties\1.1 directories, located in ClearQuest\packages CodePage=1;20127 * After .ini files are updated, re-register packages : (assume ClearQuest 7.1 default location in the example, please update paths when required) packageutil registerpackage EmailNotification 1.3 -unregister packageutil registerpackage EmailNotification 1.2 -unregister packageutil registerpackage EmailNotification 1.1 -unregister packageutil registerpackage EmailNotification 1.0 -unregister packageutil registerpackage UDBProperties 1.1 -unregister packageutil registerpackage UDBProperties 1.0 -unregister packageutil registerpackage UDBProperties 1.1 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\UDBProperties\1.1" packageutil registerpackage EmailNotification 1.3 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\EmailNotification\1.3" The error message will disappear. If you install package in the new schema repository, it will appear in the package list after completing steps above. You need to restart designer, BTW. (Even if you cannot see the package in the list, you can still use packageutil in command line to apply packages) It is not a critical issue, because you need to install packages and perform these steps on machines where you develop your ClearQuest schema only. There is no need to install package on the clients.</small></small> == Fixed problems == I am glad to announce that the problem with Perl socket library that caused some problems in Eclipse client in 7.0.1 is fixed. The package was successfully tested with all clients, using access and MS SQL Server backend databases and all feature levels. BTW, I would not recommend to deploy 7.1 until first service pack is released, but it is my personal opinion. [[Category:Email_Notification_Package]] ee6b18416af8a5b55c93e8e33498271c24577750 112 111 2011-09-04T13:09:32Z Paul 1 wikitext text/x-wiki = Email Notification Package and ClearQuest 7.1 = <big>'''The package was tested successfully with ClearQuest version 7.1'''</big> == Code Page Enforcement == <big><font color = "red">'''The following steps were necessary for pre-1.4 release only and no longer required!'''</font></big> <small><small>ClearQuest version 7.1 enforces Code Page settings for packages. If package already applied to your schema, you will see the following "Problem Occurred" message in the new Designer: Show registered packages failed... Failed condition: m_cp != sUnsetCodePage The error message does not tell you names of the failed packages. Please follow the steps below to fix the problem * Add the following line to the '''[General]''' section of "package.ini" files in EmailNotification\1.3 package and UDBProperties\1.1 directories, located in ClearQuest\packages CodePage=1;20127 * After .ini files are updated, re-register packages : (assume ClearQuest 7.1 default location in the example, please update paths when required) packageutil registerpackage EmailNotification 1.3 -unregister packageutil registerpackage EmailNotification 1.2 -unregister packageutil registerpackage EmailNotification 1.1 -unregister packageutil registerpackage EmailNotification 1.0 -unregister packageutil registerpackage UDBProperties 1.1 -unregister packageutil registerpackage UDBProperties 1.0 -unregister packageutil registerpackage UDBProperties 1.1 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\UDBProperties\1.1" packageutil registerpackage EmailNotification 1.3 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\EmailNotification\1.3" The error message will disappear. If you install package in the new schema repository, it will appear in the package list after completing steps above. You need to restart designer, BTW. (Even if you cannot see the package in the list, you can still use packageutil in command line to apply packages) It is not a critical issue, because you need to install packages and perform these steps on machines where you develop your ClearQuest schema only. There is no need to install package on the clients.</small></small> == Fixed problems == I am glad to announce that the problem with Perl socket library that caused some problems in Eclipse client in 7.0.1 is fixed. The package was successfully tested with all clients, using access and MS SQL Server backend databases and all feature levels. BTW, I would not recommend to deploy 7.1 until first service pack is released, but it is my personal opinion. [[Category:Email_Notification_Package]] 2c724e481cf10b5c9e22c55aa0f44077abc26599 0 42 114 2011-11-04T12:56:31Z Paul 1 Created page with "<big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === Parser Bug === Parser bug was introduced in [[Email_Notification_1.4_Release..." wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === Parser Bug === Parser bug was introduced in [[Email_Notification_1.4_Release_Notes | Email Notification 1.4 Release]] impacting ability to use user defined functions email notification fields. == Enhancements == === New Predefined variables and functions === UserLoginName predefined variable and two new predefined functions were added {| border="1" width="80%" align="left" cellpadding="5" |- | GetFieldOriginalValue | get field original value |- | GetGroupEmailAddresses | get list of email addresses for active ClearQuest group members |} <br /><br /> == Prerequisites == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be '''used''' with pre-7.0 clients as well. == Read More == * [[Email_Notification_1.4_Release_Notes | Email Notification Package Release 1.4 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] c4141ced9466d53a1f72548fc8c855cff67e76a8 0 2 115 79 2011-11-04T12:57:11Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 9a899a2f5a756632f3b9fba6b6a8e3a948c88314 118 115 2011-11-08T13:46:00Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] c498e4c61302fd90e4c48033cb20d59549f3d6ec 124 118 2011-12-15T03:04:33Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 81260178e13e8b6bea9f0263ea3dcebfedc980e1 125 124 2011-12-15T19:56:29Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''IBM-Rational VoiCE 2011''' : The Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] cb091ea0c76e4393ef9d594bc7e00232def3cddc 126 125 2011-12-15T19:57:03Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email Notification Package was successfully tested with ClearQuest version 7.1!''' : BTW, it needs to be re-registered on machines where you run ClearQuest designer. Please check [[ClearQuest_7.1]] page for details. * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 7ad139080b00901d5d9cd48e6e89a4a5cee68029 128 126 2012-02-24T21:02:08Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 9a7735c6fe8d816e005b736f331d1ed8aed8f34b 131 128 2012-05-17T18:29:58Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] ae7b44a294f3aee0455f2837f3b0657cbc912acc 133 131 2012-05-17T18:37:37Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 04fa732b873431a241daab3edd693449e921f040 135 133 2012-05-21T17:00:57Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email Notification Package 1.5 was released!''' : The new version delivers bug fixes and few enhancements, including easier installation, access control, end-users self-subscription with optional EmailSubscription package, and others. Please check [[Email_Notification_1.5_Release_Notes | Release Notes]] for details. * '''Email Notification Package was successfully tested with ClearQuest version 8.0!''' : Email Notification 1.5 is supported * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] 952d091030b1f2e810fa7955ae0c9a4bc34e71d0 141 135 2012-08-21T12:00:31Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.6 was released''' : The new version delivers better support for non-ascii code pages. Please check [[Email_Notification_1.6_Release_Notes | Release Notes]] for details. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. <br /><br /><br /> [[Category:Rational]] cc4ce5bfb8f8dc24eadd501e6a7abeeff40fbde5 0 7 116 93 2011-11-04T13:19:03Z Paul 1 /* Predefined variable names */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. <br /> EmailSubscription is an optional package delivering end-user self-subscription functionality. '''Note:''' Staring 1.4 release, the package can be installed on ClearQuest 7.0 Designer machine, but still can be used with older clients, if necessary. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$UserLoginName''' | style="vertical-align: top" | Login name of user triggering email notification rule |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Access control = '''udb_property''' and '''Email_Notification_Rule''' records are protected using security context (udb_visibility). By default, security context field is not set, and superuser only can submit, update, or delete configuration records. You can delegate maintenance tasks by creating desirable security context records and setting PropertyDefaultSecurityGroup and NotificationDefaultSecurityGroup database properties to populate security context field automatically when records are created (records existing before setting these properties would need to be updated manually). Default security group properties also affect action permissions. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 97d1c76bdeed8af751d6f9c8cebdcc960c7db5b6 117 116 2011-11-04T13:23:12Z Paul 1 /* GetFieldOriginalValue() */ wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. <br /> EmailSubscription is an optional package delivering end-user self-subscription functionality. '''Note:''' Staring 1.4 release, the package can be installed on ClearQuest 7.0 Designer machine, but still can be used with older clients, if necessary. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$UserLoginName''' | style="vertical-align: top" | Login name of user triggering email notification rule |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetGroupEmailAddresses(<group> [, <group2> [, ... ]])=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<group>''' | style="vertical-align: top; width: 80%" | ClearQuest groups list |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> GetGroupEmailAddresses( 'Admins', 'Engineering' ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Access control = '''udb_property''' and '''Email_Notification_Rule''' records are protected using security context (udb_visibility). By default, security context field is not set, and superuser only can submit, update, or delete configuration records. You can delegate maintenance tasks by creating desirable security context records and setting PropertyDefaultSecurityGroup and NotificationDefaultSecurityGroup database properties to populate security context field automatically when records are created (records existing before setting these properties would need to be updated manually). Default security group properties also affect action permissions. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Email_Notification_Package]] 95c3aa6240c1b911b3c4c3d913e80781b4bf1b87 0 12 119 60 2011-11-13T22:33:30Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /> Starting version 1.5, '''$UserLoginName''' predefined package variable can be used instead of GetUserLoginName user-defined function<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Starting version 1.4, original value can be accessed using '''GetFieldOriginalValue''' package-defined function, but this example can be used in earlier versions of the package. Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Sending HTML Emails == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} == Sending Emails with Attachments == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } # TRUE if current record has attachment return $result; </source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> [[Category:Email_Notification_Package]] 0bd9c81acb2b83798882d6205672677e9d8cfe3e 120 119 2011-11-13T22:43:35Z Paul 1 /* Sending Emails with Attachments */ wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == Defect state updates == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /> Starting version 1.5, '''$UserLoginName''' predefined package variable can be used instead of GetUserLoginName user-defined function<br /><br /> == Using SQL query == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == SQL query and dynamically assigned message priority == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Using original field value == Starting version 1.4, original value can be accessed using '''GetFieldOriginalValue''' package-defined function, but this example can be used in earlier versions of the package. Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == Sending HTML Emails == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} == Sending Emails with Attachments == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } # TRUE if current record has attachment return $result; </source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> [[Category:Email_Notification_Package]] 588991fddbaf9df9a521d9dad20b083636b80de4 136 120 2012-06-05T18:26:25Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == '''Defect state updates''' == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /> Starting version 1.5, '''$UserLoginName''' predefined package variable can be used instead of GetUserLoginName user-defined function<br /><br /><br /> == '''Using SQL query''' == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == '''SQL query and dynamically assigned message priority''' == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Using original field value''' == Starting version 1.4, original value can be accessed using '''GetFieldOriginalValue''' package-defined function, but this example can be used in earlier versions of the package. Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Sending HTML Emails''' == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} <br /><br /> == '''Sending Emails with Attachments''' == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } # TRUE if current record has attachment return $result; </source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> == '''Sending Consolidated Queries of Reports Using Timed Notification''' == Timed notification was created to trigger alerts for individual records, but can it be used to send consolidated reports? There are few ways to achieve it. If you are using CQWeb 7.1 or later, you can employ data-pull reports and send URL to the users. No notification would be ever required in this case. Another way would be to create scheduled notification to run some queries (or reports) and send results to the users. First of all, I would like to create new record type, scheduled_queries, that might look like this {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Field Name ! width="20%" valign="top" | Field Type ! valign="top" | Description |- | width="20%" valign="top" | '''Name''' | valign="top" | SHORT_STRING | valign="top" | unique identifier of the scheduled query |- | width="20%" valign="top" | '''Frequency''' | valign="top" | SHORT_STRING | valign="top" | choice list: daily, weekly, monthly, etc |- | width="20%" valign="top" | '''Active''' | valign="top" | INT | valign="top" | active/inactive 1/0 checkbox to deactivate entry without removing it from the database |- | width="20%" valign="top" | '''Path''' | valign="top" | MULTILINE_STRING | valign="top" | path to the query in the workspace. Multiline type is preferred to avoid 254 symbols limitation |} <br /> After creating the record type, applying Email Notification package to the record, and upgrading user database, you can configure timed notifications for the new record type. The scope can include all active records of the new record type. No condition is required. The following user-defined function can be used to execute query and extract query result in the form of HTML table (we can call it "RETURN_QUERY_RESULTS_AS_HTML_TABLE"): {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RETURN_QUERY_RESULTS_AS_HTML_TABLE<br /> | valign="top" | <source lang="perl"> my $query_path = shift; # change path to UNIX style $query_path =~ s/\\+/\//g; # resulting HTML table my $table = "<TABLE BORDER=\"1\" CELLPADDING=\"10\">\n"; # query fields my @fields = (); # get workspace my $ws = $session->GetWorkSpace(); # get query definition my $qdef = $ws->GetQueryDef($query_path); my $field_defs = $qdef->GetQueryFieldDefs(); my $count = $field_defs->Count(); for( my $i = 1; $i < $count; $i++ ){ my $field_def = $field_defs->Item($i); my $name = $field_def->GetLabel(); my $type = $field_def->GetFieldType(); push(@fields, { name => $name, type => $type }); } # Create Table Header row $table .= '<TR>'; foreach my $field (@fields){ $table .= "<TH><b>$field->{name}</b></TH>"; } $table .= "</TR>\n"; # execute query my $resultset = $session->BuildResultSet($qdef); $resultset->Execute(); # create data rows while( $resultset->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ $table .= '<TR>'; for( my $i = 2; $i <= $count; $i++ ){ my $value = $resultset->GetColumnValue($i); $table .= "<TD>$value</TD>"; } $table .= "</TR>\n"; } $table .= "</TABLE>\n"; #return HTML table $@ = ''; return $table;</source> |} <br /> Then we can use it in the timed notification rule body field, something like: {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">Content-type: text/plain; charset=us-ascii</source> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text"> <HTML><BODY> something you would like to to say about scheduled query $Name RETURN_QUERY_RESULTS_AS_HTML_TABLE($Path) </BODY></HTML> </source><br /><br /> |} Timed Notification triggers the rule, all query records are selected, query executed and formatted as HTML table, and email is sent to the users. From that moment, it is easy to maintain: you can add new scheduled queries just by submitting new records of the "scheduled queries" record type and specifying new query path, and you can update content of the emails by editing queries in the workspace. <br /> [[Category:Email_Notification_Package]] 085d8e195c3792d2ebbaf38460253ae1b2a7eada 137 136 2012-06-05T18:51:15Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == '''Defect state updates''' == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /> Starting version 1.5, '''$UserLoginName''' predefined package variable can be used instead of GetUserLoginName user-defined function<br /><br /><br /> == '''Using SQL query''' == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == '''SQL query and dynamically assigned message priority''' == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Using original field value''' == Starting version 1.4, original value can be accessed using '''GetFieldOriginalValue''' package-defined function, but this example can be used in earlier versions of the package. Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Sending HTML Emails''' == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} <br /><br /> == '''Sending Emails with Attachments''' == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } # TRUE if current record has attachment return $result; </source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> == '''Sending Consolidated Queries or Reports Using Timed Notification''' == Timed notification was created to trigger alerts for individual records, but can it be used to send consolidated reports? There are few ways to achieve it. If you are using CQWeb 7.1 or later, you can employ data-pull reports and send URL to the users. No notification would be ever required in this case. Another way would be to create scheduled notification to run some queries (or reports) and send results to the users. First of all, I would like to create new record type, scheduled_queries, that might look like this {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Field Name ! width="20%" valign="top" | Field Type ! valign="top" | Description |- | width="20%" valign="top" | '''Name''' | valign="top" | SHORT_STRING | valign="top" | unique identifier of the scheduled query |- | width="20%" valign="top" | '''Frequency''' | valign="top" | SHORT_STRING | valign="top" | choice list: daily, weekly, monthly, etc |- | width="20%" valign="top" | '''Active''' | valign="top" | INT | valign="top" | active/inactive 1/0 checkbox to deactivate entry without removing it from the database |- | width="20%" valign="top" | '''Path''' | valign="top" | MULTILINE_STRING | valign="top" | path to the query in the workspace. Multiline type is preferred to avoid 254 symbols limitation |} <br /> After creating the record type, applying Email Notification package to the record, and upgrading user database, you can configure timed notifications for the new record type. The scope can include all active records of the new record type. No condition is required. The following user-defined function can be used to execute query and extract query result in the form of HTML table (we can call it "RETURN_QUERY_RESULTS_AS_HTML_TABLE"): {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RETURN_QUERY_RESULTS_AS_HTML_TABLE<br /> | valign="top" | <source lang="perl"> my $query_path = shift; # change path to UNIX style $query_path =~ s/\\+/\//g; # resulting HTML table my $table = "<TABLE BORDER=\"1\" CELLPADDING=\"10\">\n"; # query fields my @fields = (); # get workspace my $ws = $session->GetWorkSpace(); # get query definition my $qdef = $ws->GetQueryDef($query_path); my $field_defs = $qdef->GetQueryFieldDefs(); my $count = $field_defs->Count(); for( my $i = 1; $i < $count; $i++ ){ my $field_def = $field_defs->Item($i); my $name = $field_def->GetLabel(); my $type = $field_def->GetFieldType(); push(@fields, { name => $name, type => $type }); } # Create Table Header row $table .= '<TR>'; foreach my $field (@fields){ $table .= "<TH><b>$field->{name}</b></TH>"; } $table .= "</TR>\n"; # execute query my $resultset = $session->BuildResultSet($qdef); $resultset->Execute(); # create data rows while( $resultset->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ $table .= '<TR>'; for( my $i = 2; $i <= $count; $i++ ){ my $value = $resultset->GetColumnValue($i); $table .= "<TD>$value</TD>"; } $table .= "</TR>\n"; } $table .= "</TABLE>\n"; #return HTML table $@ = ''; return $table;</source> |} <br /> Then we can use it in the timed notification rule body field, something like: {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">Content-type: text/plain; charset=us-ascii</source> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text"> <HTML><BODY> something you would like to to say about scheduled query $Name RETURN_QUERY_RESULTS_AS_HTML_TABLE($Path) </BODY></HTML> </source><br /><br /> |} Timed Notification triggers the rule, all query records are selected, query executed and formatted as HTML table, and email is sent to the users. From that moment, it is easy to maintain: you can add new scheduled queries just by submitting new records of the "scheduled queries" record type and specifying new query path, and you can update content of the emails by editing queries in the workspace. <br /> [[Category:Email_Notification_Package]] 293fee3c4f4090eee9e8802240ee4469f345c865 0 6 130 80 2012-05-17T18:19:14Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === The package and supplementary scripts are available at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 69611b27d947820ed8da90ac12ef50a0aa608712 134 130 2012-05-17T18:42:21Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] f55f077ce00ab2c875fd7e03690d460fa9254319 0 43 138 2012-08-20T20:52:41Z Paul 1 Created page with "<big>'''Support of National Charsets'''</big> == International Characters in Email Messages == Most of the modern email clients support national character in the email body. Enc..." wikitext text/x-wiki <big>'''Support of National Charsets'''</big> == International Characters in Email Messages == Most of the modern email clients support national character in the email body. Encoding can be specified in the message envelope using '''Content-Type''' header. For instance, the following line added to the message header would inform email client that email body should be treated as HTML using UTF-8 character set. Content-Type: text/html; charset=utf-8 Nevertheless, what do we suppose to do with international characters in the message envelope, such as email subject or "From" email address? Depending on your environment, there are few options. === Transfer unicode characters in UTF-8 === While it was not originally supported in SMTP protocol, using UTF-8 encoding in message envelopes became standard de facto, and eventually was documented in RFCs extending SMTP protocol. In most of the environments, and for most of the modern email clients it is safe to assume that UTF-8 content can be transferred as-is, and it is default behavior for the Email Notification package. Nevertheless, you still need to specify character set using '''Content-Type''' header as described above. === Transcoding unicode characters === In some rare cases when email client or email server cannot handle UTF-8 encoded characters in the message envelope, a workaround documented in the [http://tools.ietf.org/html/rfc2047|RFC 2047] can be used. The following is an example of user-defined function that can be used to encode UTF-8 strings using Base64 encoding and presenting it in the format specified in the RFC. <br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_Encode_Envelope<br /> | valign="top" | <source lang="perl"> my $string = shift; require utf8; require MIME::Base64; utf8::encode($string); $string = MIME::Base64::encode($string); return "=?UTF-8?B?$string?="; </source> |} <br /> When udb_property record is submitted, this user-defined function can be used to safely encode envelope fields that can contain unicode characters, for instance message subject: RT_Encode_Envelope("Defect $ID - $headline") [[Category:ClearQuest]] [[Category:Email_Notification_Package]] c2bde3140e69269911b8357c0549b86714aa41fe 139 138 2012-08-20T20:54:38Z Paul 1 wikitext text/x-wiki <big>'''Support of National Charsets'''</big> == International Characters in Email Messages == Most of the modern email clients support national character in the email body. Encoding can be specified in the message envelope using '''Content-Type''' header. For instance, the following line added to the message header would inform email client that email body should be treated as HTML using UTF-8 character set. Content-Type: text/html; charset=utf-8 Nevertheless, what do we suppose to do with international characters in the message envelope, such as email subject or "From" email address? Depending on your environment, there are few options. === Transfer unicode characters in UTF-8 === While it was not originally supported in SMTP protocol, using UTF-8 encoding in message envelopes became standard de facto, and eventually was documented in RFCs extending SMTP protocol. In most of the environments, and for most of the modern email clients it is safe to assume that UTF-8 content can be transferred as-is, and it is default behavior for the Email Notification package. Nevertheless, you still need to specify character set using '''Content-Type''' header as described above. === Transcoding unicode characters === In some rare cases when email client or email server cannot handle UTF-8 encoded characters in the message envelope, a workaround documented in the [http://tools.ietf.org/html/rfc2047|RFC 2047] can be used. The following is an example of user-defined function that can be used to encode UTF-8 strings using Base64 encoding and presenting it in the format specified in the RFC. <br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_Encode_Envelope<br /> | valign="top" | <source lang="perl">my $string = shift; require utf8; require MIME::Base64; utf8::encode($string); $string = MIME::Base64::encode($string); return "=?UTF-8?B?$string?="; </source> |} <br /> When udb_property record is submitted, this user-defined function can be used to safely encode envelope fields that can contain unicode characters, for instance message subject: RT_Encode_Envelope("Defect $ID - $headline") [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 19eae5f0ce2b74e9b0e7da4439b88f2e0e10ec6d 0 44 140 2012-08-20T21:14:20Z Paul 1 Created page with "<big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages..." wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] b67f72c4a20bee3ac3fa72c575ddc0fcdf7987cf 142 140 2012-08-21T12:12:55Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. <br /> == Other Notes == === Supplementary scripts === Supplementary script, such as Delivery Script for Queue delivery mode and Timed Notification script for reminders need to be updated in order to support non-ascii databases. New versions are available for download from [http://store.cqadmin.com/index.php/clearquest.html CQAdmin store]. == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 0ed12657c0fa03415ab9ef725f38eded05c6eab6 143 142 2012-08-21T12:13:24Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. <br /> == Other Notes == === Supplementary scripts === Supplementary script, such as Delivery Script for Queue delivery mode and Timed Notification script for reminders, need to be updated in order to support non-ascii databases. New versions are available for download from [http://store.cqadmin.com/index.php/clearquest.html CQAdmin store]. == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3a1f062acdb7b7b342d503f733f214606fa4245d 0 45 144 2012-11-21T21:00:07Z Paul 1 Created page with "<big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = It is NOT a solution that is provided and supported b..." wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = It is NOT a solution that is provided and supported by IBM-Rational. Dynamic list editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provide unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most important) Web client. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. == Installation Instruction == The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When configuration is completed, users with "Dynamic List Admin" privilege or super users can modify content of the Dynamic Lists using editor interface. === Installing ClearQuest Schema Update === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that ClearQuest schema is checked in, and there are no pending changes that have not been applied to the user database. * Open command line tool, (Start->Run "cmd") and change directory to the location where integration package was unpacked * Import integration using "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that schema update was imported and no issues were detected == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 6812f9f8fbb926670a029859e0cc9b020adc0e5b 6 46 145 2012-11-22T01:41:09Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 47 146 2012-11-22T01:53:20Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 48 147 2012-11-22T01:54:55Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 49 148 2012-11-22T01:55:17Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 50 149 2012-11-22T02:04:10Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 51 150 2012-11-22T02:04:29Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 52 151 2012-11-22T02:04:49Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 53 152 2012-11-22T03:14:24Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 54 153 2012-11-22T03:14:52Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 55 154 2012-11-22T03:15:12Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 56 155 2012-11-22T03:25:53Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 57 156 2012-11-22T03:26:22Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 58 157 2012-11-22T03:26:44Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 45 158 144 2012-11-22T03:26:54Z Paul 1 /* Dynamic List Editor */ wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = It is NOT a solution that is provided and supported by IBM-Rational. Dynamic list editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provide unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most important) Web client. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators are working with the stateless records, and when update is completed and records are submitted to the database, correspondent dynamic lists are updated automatically. == Installation Instruction == The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When configuration is completed, users with "Dynamic List Admin" privilege or super users can modify content of the Dynamic Lists using editor interface. === Installing ClearQuest Schema Update === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that ClearQuest schema is checked in, and there are no pending changes that have not been applied to the user database. * Open command line tool, (Start->Run "cmd") and change directory to the location where integration package was unpacked * Import integration using "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that schema update was imported and no issues were detected [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. In the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to. and select "Upgrade Database" from the context menu. [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be done from a ClearQuest client. You can use any client of your choice. In the instructions we will be using ClearQuest Web client, version 8.0. Login as an administrator, and submit new record of the "Dynamic_List" type [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names in the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit record to the database ==== Creating Dynamic List Administration Query ==== Now, you need to create a simple query that will be used by the Dynamic Lists administrators. Right click on the folder were you are going to save the query and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide query name, for instance, "Dynamic Lists", add "Name" field to the presentation/display section, and specify "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run "Dynamic Lists" query that we created on the previous step. Verify that the first Dynamic List record is in the result set. Open the record. In the "Utilities" section, select "SyncAllLists" action. By default, the action is opened for ClearQuest administrators only. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when ClearQuest record already exists, its content is updated from the dynamic list * when ClearQuest record does not exist, new record is created * when dynamic list for existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no errors occur, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 323059cf098b3199d14734604bf666a018ea80dc 160 158 2012-11-22T15:00:44Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = It is NOT a solution that is provided and supported by IBM-Rational. Dynamic list editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provide unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most important) Web client. In addition, it adds basic audit capabilities that can be enhanced using Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators are working with the stateless records, and when update is completed and records are submitted to the database, correspondent dynamic lists are updated automatically. == Installation Instruction == The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When configuration is completed, users with "Dynamic List Admin" privilege or super users can modify content of the Dynamic Lists using editor interface. === Installing ClearQuest Schema Update === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that ClearQuest schema is checked in, and there are no pending changes that have not been applied to the user database. * Open command line tool, (Start->Run "cmd") and change directory to the location where integration package was unpacked * Import integration using "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that schema update was imported and no issues were detected [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. In the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to. and select "Upgrade Database" from the context menu. [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be done from a ClearQuest client. You can use any client of your choice. In the instructions we will be using ClearQuest Web client, version 8.0. Login as an administrator, and submit new record of the "Dynamic_List" type [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names in the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit record to the database ==== Creating Dynamic List Administration Query ==== Now, you need to create a simple query that will be used by the Dynamic Lists administrators. Right click on the folder were you are going to save the query and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide query name, for instance, "Dynamic Lists", add "Name" field to the presentation/display section, and specify "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run "Dynamic Lists" query that we created on the previous step. Verify that the first Dynamic List record is in the result set. Open the record. In the "Utilities" section, select "SyncAllLists" action. By default, the action is opened for ClearQuest administrators only. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when ClearQuest record already exists, its content is updated from the dynamic list * when ClearQuest record does not exist, new record is created * when dynamic list for existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no errors occur, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Administering Dynamic Lists == When all Dynamic_List records are populated, List administrators can start using them to modify content of the correspondent dynamic lists. Most of the time, "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration process: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows to create new records when new Dynamic List added to the schema. Alternatively, you can use "SyncAllLists" utility action to synchronize all records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When action is initialized the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows to delete existing Dynamic_List records. For instance, when correspondent dynamic list was removed from the schema. Alternatively, you can use "SyncAllLists" utility action to synchronize all records at once after database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh ClearQuest query or even close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves content of the current ClearQuest records into correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from the external source. |- | SyncAllLists | Utilities / Script | Super User | The action syncs ClearQuest records with the correspondent dynamic lists: * when ClearQuest record already exists, its content is updated from the dynamic list * when ClearQuest record does not exist, new record is created * when dynamic list for existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == For performance, ClearQuest caches content of dynamic lists. When you update content of the dynamic lists using native tools, the updates are not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see them. Dynamic list editor is using actual dynamic list as a primary trusted source of data for the records. When you initiate record update, the record content is loaded from the dynamic list first. In the environment when dynamic lists are actively updated from many clients simultaneously, it might cause changes overwriting, because cached values could be used instead. In so changing environment, it is recommended to re-login to the database before starting dynamic list modification (the same issue exist even when you are using native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when ClearQuest full client is not installed on Dynamic List Admins' machines, and they are using Editor's Web Client capability to modify lists only), you can select ClearQuest records as a trusted source of data for the dynamic lists. In order to do it, you need to remove "Update" action initialization hook of the Dynamic_List record type, and upgrade user database to apply changes. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 48d4341796e3c727b415e69172a2da62cdf7cc8d 161 160 2012-11-22T15:26:42Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = It is NOT a solution that is provided and supported by IBM-Rational. Dynamic list editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most important) Web client. In addition, it adds basic audit capabilities that can be enhanced using Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators are working with the stateless records, and when update is completed and records are submitted to the database, correspondent dynamic lists are updated automatically. == Installation Instruction == The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When configuration is completed, users with "Dynamic List Admin" privilege or super users can modify content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Installing ClearQuest Schema Update === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that ClearQuest schema is checked in, and there are no pending schema changes that have not been applied to the user database. * Open command line tool, (Start->Run "cmd") and change directory to the location where the integration package was extracted. * Import integration using "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that the schema update was imported and no issues were detected. [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to. and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select "Upgrade Database..." option from the database menu and select your user database). [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be done from a ClearQuest client. You can use any client of your choice. In the instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit new record of the "Dynamic_List" type: [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names from the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list values will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit record to the database ==== Creating Dynamic List Administration Query ==== Now, you need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder were you are going to save the query and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide query name, for instance, "Dynamic Lists", add "Name" field to the presentation/display section, and specify "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in "Utilities" section, chose "SyncAllLists" action. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when ClearQuest record already exists, its content is updated from the dynamic list * when ClearQuest record does not exist, new record is created * when dynamic list for existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no errors occur, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Administering Dynamic Lists == When all Dynamic_List records are populated, List administrators can start using the query you created and Dynamic_Lists records to modify content of the linked dynamic lists. Most of the time, "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows to create new records when new Dynamic List added to the ClearQuest schema. Instead, you can use "SyncAllLists" utility action to synchronize all records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When action is initialized the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows to delete existing Dynamic_List records. For instance, when correspondent dynamic list was removed from the schema. Alternatively, you can use "SyncAllLists" utility action to synchronize all records at once after database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh ClearQuest query or even close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves content of the current ClearQuest records into correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from the external source. |- | SyncAllLists | Utilities / Script | Super User | The action syncs ClearQuest records with the correspondent dynamic lists: * when ClearQuest record already exists, its content is updated from the dynamic list * when ClearQuest record does not exist, new record is created * when dynamic list for existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches content of dynamic lists. When you update content of the dynamic lists using native tools, the updates are not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, dynamic list editor is using actual dynamic list as a primary trusted source of data for the records. When you initiate record update, the record content is loaded from the dynamic list first. In the environment when dynamic lists are actively updated from many clients simultaneously, it might cause changes overwriting, because cached list values could be used by ClearQuest. In so changing environment, it is recommended to re-login to the database before starting dynamic list modification (the same issue exists when you are using native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when ClearQuest full client is not installed on Dynamic List Admins' machines, and they are using Editor's Web Client capability to modify lists only), you can select ClearQuest records as a trusted source of data for the dynamic lists. In order to do it, you need to remove "Update" action initialization hook of the Dynamic_List record type, and upgrade user database to apply changes. It would ensure that most accurate data is used for lists modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 902f8502de16e2289480be827086459b8869f956 162 161 2012-11-23T00:37:35Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically. == Installation Instruction == The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Installing ClearQuest Schema Update === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save the downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database. * Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted. * Import integration using the "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that the schema update was imported and no issues were detected. [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database). [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit a new record of the "Dynamic_List" type: [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names from the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list values will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit the record to the database ==== Creating Dynamic List Administration Query ==== Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no error occurred, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with their proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Administering Dynamic Lists == When all the Dynamic_List records are populated, List Administrators can start using the query you created and Dynamic_Lists records to modify the content of the linked dynamic lists. Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves the content of the current ClearQuest records into a correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source. |- | SyncAllLists | Utilities / Script | Super User | This action syncs ClearQuest records with their correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 279d870b27d96a4d75f78537a85ce0add8cf9fc3 14 59 159 2012-11-22T03:41:28Z Paul 1 Created page with "Dynamic List Editor and related materials" wikitext text/x-wiki Dynamic List Editor and related materials fbc1489a96c53bca34b6b364a83c90762ad45998 6 46 163 145 2012-11-23T14:16:59Z Paul 1 uploaded a new version of &quot;[[File:Dynamic List Editor.png]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 2 164 141 2012-11-23T19:32:16Z Paul 1 /* Resources */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. You need to register to create or edit wiki pages only. == Latest news == * '''Email Notification Package 1.6 was released''' : The new version delivers better support for non-ascii code pages. Please check [[Email_Notification_1.6_Release_Notes | Release Notes]] for details. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. <br /><br /><br /> [[Category:Rational]] 30e994588a21534565b804b01e97fc789966b762 165 164 2012-11-23T19:32:48Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package 1.6 was released''' : The new version delivers better support for non-ascii code pages. Please check [[Email_Notification_1.6_Release_Notes | Release Notes]] for details. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) * '''Email notification package support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. <br /><br /><br /> [[Category:Rational]] a13161127a0b6c04ff82a0652ed2d8bc414fcf94 180 165 2013-01-18T14:41:31Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of Ready for IBM Rational software. The package met the requirements for the IBM Software Delivery Platform level of the program. It is "Ready for IBM-Rational Software" * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] 058ee3c5fd7ff155fc34bb60a201fc85b94b92ec 181 180 2013-01-18T14:41:50Z Paul 1 /* Resources */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of Ready for IBM Rational software. The package met the requirements for the IBM Software Delivery Platform level of the program. It is "Ready for IBM-Rational Software" * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] d931de67b737a2d7f57db31c8b471e8f00f67d52 193 181 2013-01-19T03:18:11Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of Ready for IBM Rational software. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] 1f3df7e53c907195a33b81cd7e638d2d8accd3b9 194 193 2013-01-19T03:18:40Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of Ready for IBM Rational software. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] 6133278cc48d64838206c082f700f0a0f8309491 196 194 2013-01-19T19:29:21Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of Ready for IBM Rational software. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] 86f04ee6b65069b9b5eda4422e5f350b348b27a5 0 6 166 134 2012-11-23T20:53:56Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details. === The Distribution === The distribution is available at [http://store.cqadmin.com/index.php/dynamic-list-editor-for-ibm-rational-clearquest.html CQAdmin store]. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] 62884514517c92787c4ee8b5afa0bcf1ec86c70b 177 166 2012-12-21T13:06:35Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details. === The Distribution === The distribution is available at [http://store.cqadmin.com/index.php/dynamic-list-editor-for-ibm-rational-clearquest.html CQAdmin store]. == Download Instructions == === Download Links in Email === In order to download products, you have to register at [http://store.cqadmin.com/index.php/ CQAdmin store] and place your order. In few minutes you will receive a confirmation email containing download links. [[File:email_links.png|center]] === Downloading Products from the Store === Alternatively, you could use "My Downloadable Products" section of your account. You would need to click on the download link right to the order title. [[File:store_links.png|center]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] ac33c8bd14d09a12ce2219b6cea5203d33757ee3 178 177 2012-12-21T13:43:34Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions. === The Package === The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details. === The Distribution === The distribution is available at [http://store.cqadmin.com/index.php/dynamic-list-editor-for-ibm-rational-clearquest.html CQAdmin store]. == Download Instructions == === Download Links in Email === In order to download products, you have to register at [http://store.cqadmin.com/index.php/ CQAdmin store] and place your order. In few minutes you will receive a confirmation email containing download links. [[File:email_links.png]] === Downloading Products from the Store === Alternatively, you could use "My Downloadable Products" section of your account. You would need to click on the download link right to the order title. [[File:store_links.png]] === '''Microsoft Internet Explorer''' users === '''Microsoft Internet Explorer''' users might need to use "Save As" option to download file correctly: * Right click on the download link * Select "Save As" option from the context menu * Save downloaded file as "some_name.zip" [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] b0bb468ea3b794d5f0493c23265cd0a2ac899c75 6 20 167 32 2012-12-05T01:04:23Z Paul 1 uploaded a new version of &quot;[[File:Image002.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 21 168 33 2012-12-05T01:05:11Z Paul 1 uploaded a new version of &quot;[[File:Image004.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 169 168 2012-12-05T01:05:15Z Paul 1 uploaded a new version of &quot;[[File:Image004.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 170 169 2012-12-05T01:06:17Z Paul 1 uploaded a new version of &quot;[[File:Image004.jpg]]&quot;: Reverted to version as of 01:05, 5 December 2012 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 22 171 34 2012-12-05T01:07:31Z Paul 1 uploaded a new version of &quot;[[File:Image006.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 23 172 35 2012-12-05T01:08:11Z Paul 1 uploaded a new version of &quot;[[File:Image008.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 24 173 36 2012-12-05T01:08:49Z Paul 1 uploaded a new version of &quot;[[File:Upgrade udb.jpg]]&quot; wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 8 174 66 2012-12-05T01:11:15Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you '''created backup''' to be able to roll back the change if necessary. It is strongly recommended to test it on a test copy of your schema first. Also, it would make sense to use it with the same database vendor as your production database. In this case, you can minimize risks and safely deploy the package to your production schema and database later. Are you scared yet? == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.6 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] and select package version you would like to apply. == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Configuring Package == Proceed to [[EmailNotification_Creating_First_Notification_Rule | Creating First Notification Rule]] section. [[Category:Email_Notification_Package]] e7ef1033ca2dad482ca1a23a8c185d01485a6981 6 60 175 2012-12-21T13:01:19Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 61 176 2012-12-21T13:01:42Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 62 179 2013-01-18T14:37:32Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 5 182 132 2013-01-18T14:45:41Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> [[File:R4_Rational.jpg|right|140px]] Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Support == : ClearQuest Email Notification package is [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html officially supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Email_Notification_Package]] a86b412bba588471edf785e819c6f4ed38c85bd9 6 63 183 2013-01-18T17:57:05Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 64 184 2013-01-18T18:09:52Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 65 185 2013-01-18T18:13:53Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 66 186 2013-01-18T18:19:38Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 67 187 2013-01-18T18:34:03Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 68 188 2013-01-18T18:40:46Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 69 189 2013-01-18T18:48:35Z Paul 1 Created page with "<big>'''User Administration Tool Installation'''</big> == Planing the Installation == User Administration Tool for IBM-Rational ClearQuest is a ClearQuest database. The installe..." wikitext text/x-wiki <big>'''User Administration Tool Installation'''</big> == Planing the Installation == User Administration Tool for IBM-Rational ClearQuest is a ClearQuest database. The installer will add a custom schema to your schema repository, create user database associated with the schema, and load all data. Before you proceed, you need to collect: * Physical Database information of empty database (DB vendor, server, database name, database user account, and connect options). The database needs to be created in advance (unless you are going to use Microsoft Access). * Email notification settings - SMTP server name and email user credentials (if password authentication is required with SMTP relay). You can check [[Package_configuration | Email Notification Package Configuration]] page for additional information. * Obtain local administrative rights on the machine where you are going to perform the installation. * Create (or use an existing) ClearQuest account with Super User right that will be used for user account management. It is recommended to use ClearQuest authentication for the account to avoid problems related to password expiration. == Backup Schema Repository Database == It is always a good idea to create a backup before you making any change to the schema repository to roll back the change if necessary, and I strongly recommend to install the tool in your testing environment first: you would be able to validate that it is compatible with your environment and database vendor. It would minimize risks associated with deployment of the tool in your production environment later. == Installing User Admin Tool == You can install the tool using any machine that has IBM-Rational ClearQuest installed and ClearQuest connection configured. First, unpack User Administration Tool distribution to local or network drive (you cannot start installation from network location referenced via UNC path), and launch '''install.bat''' located in the root of the distribution. [[File:user_admin_install.png|none]] <br />On Windows 7 and Windows 2008 machines you need to select "Run as Administrator" option explicitly, and allow making changes [[File:user_admin_install_2.png|none]] <br />Login to the ClearQuest using connection (dbset) that you would like to enable for user administration using Super User account you created on the "planning..." step. [[File:user_admin_install_login.png|none]] <br />Provide required information to create ClearQuest User Administration database. Depending on your database vendor and environment, you might need to provide additional connection options. Please check ClearQuest administration manual for details. If you aborted the installation for any reason after user database was created, you would be allowed to select user database created earlier instead of creating a new one. [[File:user_admin_db_settings.png|none]] <br />Verify that you entered all information and click on "Create DB" button. The installer will start creating user database and importing all user data. There is no progress indicator, please be patient. Depending on database server load and number of user accounts the initial load might take significant time. For example, in my local environment it takes about 15 minutes to load 3000 users and groups. When user database is created and data import is completed, the installer will offer you to configure email notification setting. Please provide required information and save settings. The installer will validate SMTP server connectivity. [[File:user_admin_en_config.png|none]] <br />It is the last step in the installation procedure, and no error occurred, you should receive the following confirmation. [[File:user_admin_install_completed.png|none]] <br />Congratulations! You have completed your installation. Log in to the ClearQuest database you created and you can start using it immediately. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_User_Accounts | Managing ClearQuest User Accounts]]. * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 0f077a86ad94e95bc504e235a9d07e5e9ed19a99 198 189 2013-01-21T20:50:16Z Paul 1 /* Additional Information */ wikitext text/x-wiki <big>'''User Administration Tool Installation'''</big> == Planing the Installation == User Administration Tool for IBM-Rational ClearQuest is a ClearQuest database. The installer will add a custom schema to your schema repository, create user database associated with the schema, and load all data. Before you proceed, you need to collect: * Physical Database information of empty database (DB vendor, server, database name, database user account, and connect options). The database needs to be created in advance (unless you are going to use Microsoft Access). * Email notification settings - SMTP server name and email user credentials (if password authentication is required with SMTP relay). You can check [[Package_configuration | Email Notification Package Configuration]] page for additional information. * Obtain local administrative rights on the machine where you are going to perform the installation. * Create (or use an existing) ClearQuest account with Super User right that will be used for user account management. It is recommended to use ClearQuest authentication for the account to avoid problems related to password expiration. == Backup Schema Repository Database == It is always a good idea to create a backup before you making any change to the schema repository to roll back the change if necessary, and I strongly recommend to install the tool in your testing environment first: you would be able to validate that it is compatible with your environment and database vendor. It would minimize risks associated with deployment of the tool in your production environment later. == Installing User Admin Tool == You can install the tool using any machine that has IBM-Rational ClearQuest installed and ClearQuest connection configured. First, unpack User Administration Tool distribution to local or network drive (you cannot start installation from network location referenced via UNC path), and launch '''install.bat''' located in the root of the distribution. [[File:user_admin_install.png|none]] <br />On Windows 7 and Windows 2008 machines you need to select "Run as Administrator" option explicitly, and allow making changes [[File:user_admin_install_2.png|none]] <br />Login to the ClearQuest using connection (dbset) that you would like to enable for user administration using Super User account you created on the "planning..." step. [[File:user_admin_install_login.png|none]] <br />Provide required information to create ClearQuest User Administration database. Depending on your database vendor and environment, you might need to provide additional connection options. Please check ClearQuest administration manual for details. If you aborted the installation for any reason after user database was created, you would be allowed to select user database created earlier instead of creating a new one. [[File:user_admin_db_settings.png|none]] <br />Verify that you entered all information and click on "Create DB" button. The installer will start creating user database and importing all user data. There is no progress indicator, please be patient. Depending on database server load and number of user accounts the initial load might take significant time. For example, in my local environment it takes about 15 minutes to load 3000 users and groups. When user database is created and data import is completed, the installer will offer you to configure email notification setting. Please provide required information and save settings. The installer will validate SMTP server connectivity. [[File:user_admin_en_config.png|none]] <br />It is the last step in the installation procedure, and no error occurred, you should receive the following confirmation. [[File:user_admin_install_completed.png|none]] <br />Congratulations! You have completed your installation. Log in to the ClearQuest database you created and you can start using it immediately. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] e1c2c02bc15b47acee18c095a810a5f7a5c8da89 0 70 190 2013-01-18T23:29:16Z Paul 1 Created page with "<big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or add..." wikitext text/x-wiki <big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or adding customizations, such as setting field default values or adding enhanced field or action validation, without schema modification. Its configuration is stored in the ClearQuest database using udb_property records. These records are protected using Security Context feature and not visible to regular users. In addition, the most critical data is encrypted. You can find currently set property values in the public workspace query "Public Queries\Database_Settings\Properties". {| class="wikitable" cellpadding="10" ! align="left"| Property Name ! Default Value ! Secure ! Comments |- | admin_creds | | Yes | It is a "secure" property that carries administrative user credentials in username/password format. This user account is used to communicate to the master user repository to query or sync users and groups. |- |CONFIG_LOAD_EVERYONE_GROUP |false |No |A built-in "Everyone" group was introduced with ClearQuest Feature Level 7. This group cannot be modified, and by default, it is not loaded to the User Administration tool. This behavior can be changed by setting this property to non-zero value. There is no reason to lad built-in "Everyone" group, but if you are using pre-FL7 database that has group with this name, it might be a solution. |- |CONFIG_MULTISITE_ENABLED |false |No |Enables Multisite resource-consuming validations, such as mastership of the groups that you would like to add user to. It might impact performance. Do not set it, unless you are using the tool in multisited environment and you are planning to use the tool from many sites simultaniously. |- |CONFIG_OBEY_MS_ON_CREATE |false |No |By default, during initial load and synchronizations, all users are loaded into the database regardless of mastership. This behavior can be changed by setting the property to non-zero value. In this case, the load will be limited to locally mastered users and groups, but it will require you to perform load from each site. |- |CONFIG_SUPER_USER_GROUP CONFIG_USER_ADMIN_GROUP CONFIG_PASSWORD_RESET_GROUP | |No |By default, ClearQuest user with Super User or User Admin privilege is allowed to create and update users and groups, and Super User only is allowed to delete user or group records (when no associated account exists in the master repository). It can be changed by setting the corresponding property to ClearQuest group name. Members of the group would carry the privilege withing the tool, but they would not be able to use the standard ClearQuest user administration utility (to avoid possible problems and necessity of synchronization). Members of the group set in the CONFIG_PASSWORD_RESET_GROUP are allowed to reset user's password only (execute "Password_Reset" action). |- |CONFIG_GROUP_ADMIN_SUFFIX | |No |You can use this property to permit some users to administer specific groups only (add or remove existing users and groups). For instance, by setting this property to "_ADM", you would allow members of Some_Group_Name_ADM to administer Some_Group_Name ClearQuest group without granting them any other permissions. |- |CONFIG_GENERATE_PASSWORD |false |No |When this property is set to non-zero value, and you create user account with ClearQuest authentication leaving password blank, the system will generate random password and include it in the user notification (it is kept in the "NEW_USER_PASSWORD" property). |- |CONFIG_GENERATE_PASSWORD_CHARACTERS |0-9a-zA-Z |No |Characters used by password generator |- |CONFIG_GENERATE_PASSWORD_LENGTH |8 |No |Length of the generated password |- |CONFIG_USER_PROFILE_FIELDS |UserPrivileges Groups DB_Subscription_Type DB_Subscription |No |User account can be updated using other account as a profile. For example, you can create a user that would mirror access somebody else user account permissions. By default, the other user account User Privileges, Groups, Database subscription type and subscribed databases are copied, but it can be changed by setting CONFIG_USER_PROFILE_FIELDS property with desired set of fields in one-field-per-line format. |- |DEFAULT_USERPRIVILEGES DEFAULT_AUTHTYPE DEFAULT_DB_SUBSCRIPTION_TYPE DEFAULT_DB_SUBSCRIPTION DEFAULT_GROUPS_REQUESTED DEFAULT_PROFILE_CHOICE DEFAULT_PROFILE_OPERATION | |No |These properties allow to configure user and group default field values. When you start creating new user, it can be initialized with LDAP authentication type, specific set of user privileges, and be subscribed to specific set of user databases. |- |CONFIG_ENABLE_CUSTOM_FIELD_VALIDATION |false |No |This property enables check for custom field validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_FIELD_NAME VALIDATE_FIELD_LOGIN_NAME VALIDATE_FIELD_FULLNAME VALIDATE_FIELD_PHONE VALIDATE_FIELD_EMAIL VALIDATE_FIELD_USERPRIVILEGES VALIDATE_FIELD_PASSWORD VALIDATE_FIELD_DB_SUBSCRIPTION_TYPE VALIDATE_FIELD_DB_SUBSCRIPTION VALIDATE_FIELD_GROUPS_REQUESTED VALIDATE_FIELD_USERS VALIDATE_FIELD_GROUPS | |No |These properties can contain custom validation hook code for User and Group record fields. There is no need to define all of them when custom validation is enabled. You can define required scripts only. The script is the same as a validation Perl hook: it can use $session and $entity global variables and entire CQPerl API. In case of validation error, '''$result''' variable needs to be set with validation error message. You can take VALIDATE_FIELD_EMAIL property as an example. It checks that user's email address was provided in correct format: <source lang="perl"> my $email = $entity->GetFieldValue($fieldname)->GetValue(); if( $email !~ /^[\w\-\.]+\@[\w\-\.]+$/){ $result = "Email address needs to be specified in email\@mycompany.com format!"; } </source> Please note that DB subscription and type properties are the same for both Group and User record types. You can check record type within the custom hook using <source lang="perl">$entity->GetEntityDefName()</source> API call. |- |CONFIG_ENABLE_CUSTOM_ACTION_VALIDATION |false |No |This property enables check for custom action validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_ACTION_<ACTION_NAME> | |No |These properties contains custom validation code. Custom validation can be written in Perl, using CQPerl API and $session and $entity global variables. Error message should be assigned to the '''$result''' variable. |- |MAX_LENGTH_FULLNAME MAX_LENGTH_PHONE MAX_LENGTH_EMAIL | 50 | No | Currently, ClearQuest user full name, phone and email fields are limited to 50 characters. If the limit is changed in the future releases, this property can be set to indicate the new limit. |- |} [[Category:User_Admin_Tool]] 344469bc6ccc9c568883972ca1634757bebdb4a4 191 190 2013-01-18T23:32:42Z Paul 1 wikitext text/x-wiki <big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or adding customizations, such as setting field default values or adding enhanced field or action validation, without schema modification. Its configuration is stored in the ClearQuest database using udb_property records. These records are protected using Security Context feature and not visible to regular users. In addition, the most critical data is encrypted. You can find currently set property values in the public workspace query "Public Queries\Database_Settings\Properties". {| class="wikitable" cellpadding="10" ! align="left"| Property Name ! Default Value ! Secure ! Comments |- | admin_creds | |align="center"| Yes | It is a "secure" property that carries administrative user credentials in username/password format. This user account is used to communicate to the master user repository to query or sync users and groups. |- |CONFIG_LOAD_EVERYONE_GROUP |align="center"|false |align="center"|No |A built-in "Everyone" group was introduced with ClearQuest Feature Level 7. This group cannot be modified, and by default, it is not loaded to the User Administration tool. This behavior can be changed by setting this property to non-zero value. There is no reason to lad built-in "Everyone" group, but if you are using pre-FL7 database that has group with this name, it might be a solution. |- |CONFIG_MULTISITE_ENABLED |align="center"|false |align="center"|No |Enables Multisite resource-consuming validations, such as mastership of the groups that you would like to add user to. It might impact performance. Do not set it, unless you are using the tool in multisited environment and you are planning to use the tool from many sites simultaniously. |- |CONFIG_OBEY_MS_ON_CREATE |align="center"|false |align="center"|No |By default, during initial load and synchronizations, all users are loaded into the database regardless of mastership. This behavior can be changed by setting the property to non-zero value. In this case, the load will be limited to locally mastered users and groups, but it will require you to perform load from each site. |- |CONFIG_SUPER_USER_GROUP CONFIG_USER_ADMIN_GROUP CONFIG_PASSWORD_RESET_GROUP | |align="center"|No |By default, ClearQuest user with Super User or User Admin privilege is allowed to create and update users and groups, and Super User only is allowed to delete user or group records (when no associated account exists in the master repository). It can be changed by setting the corresponding property to ClearQuest group name. Members of the group would carry the privilege withing the tool, but they would not be able to use the standard ClearQuest user administration utility (to avoid possible problems and necessity of synchronization). Members of the group set in the CONFIG_PASSWORD_RESET_GROUP are allowed to reset user's password only (execute "Password_Reset" action). |- |CONFIG_GROUP_ADMIN_SUFFIX | |align="center"|No |You can use this property to permit some users to administer specific groups only (add or remove existing users and groups). For instance, by setting this property to "_ADM", you would allow members of Some_Group_Name_ADM to administer Some_Group_Name ClearQuest group without granting them any other permissions. |- |CONFIG_GENERATE_PASSWORD |align="center"|false |align="center"|No |When this property is set to non-zero value, and you create user account with ClearQuest authentication leaving password blank, the system will generate random password and include it in the user notification (it is kept in the "NEW_USER_PASSWORD" property). |- |CONFIG_GENERATE_PASSWORD_CHARACTERS |align="center"|0-9a-zA-Z |align="center"|No |Characters used by password generator |- |CONFIG_GENERATE_PASSWORD_LENGTH |align="center"|8 |align="center"|No |Length of the generated password |- |CONFIG_USER_PROFILE_FIELDS |align="center"|UserPrivileges Groups DB_Subscription_Type DB_Subscription |align="center"|No |User account can be updated using other account as a profile. For example, you can create a user that would mirror access somebody else user account permissions. By default, the other user account User Privileges, Groups, Database subscription type and subscribed databases are copied, but it can be changed by setting CONFIG_USER_PROFILE_FIELDS property with desired set of fields in one-field-per-line format. |- |DEFAULT_USERPRIVILEGES DEFAULT_AUTHTYPE DEFAULT_DB_SUBSCRIPTION_TYPE DEFAULT_DB_SUBSCRIPTION DEFAULT_GROUPS_REQUESTED DEFAULT_PROFILE_CHOICE DEFAULT_PROFILE_OPERATION | |align="center"|No |These properties allow to configure user and group default field values. When you start creating new user, it can be initialized with LDAP authentication type, specific set of user privileges, and be subscribed to specific set of user databases. |- |CONFIG_ENABLE_CUSTOM_FIELD_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom field validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_FIELD_NAME VALIDATE_FIELD_LOGIN_NAME VALIDATE_FIELD_FULLNAME VALIDATE_FIELD_PHONE VALIDATE_FIELD_EMAIL VALIDATE_FIELD_USERPRIVILEGES VALIDATE_FIELD_PASSWORD VALIDATE_FIELD_DB_SUBSCRIPTION_TYPE VALIDATE_FIELD_DB_SUBSCRIPTION VALIDATE_FIELD_GROUPS_REQUESTED VALIDATE_FIELD_USERS VALIDATE_FIELD_GROUPS | |align="center"|No |These properties can contain custom validation hook code for User and Group record fields. There is no need to define all of them when custom validation is enabled. You can define required scripts only. The script is the same as a validation Perl hook: it can use $session and $entity global variables and entire CQPerl API. In case of validation error, '''$result''' variable needs to be set with validation error message. You can take VALIDATE_FIELD_EMAIL property as an example. It checks that user's email address was provided in correct format: <source lang="perl"> my $email = $entity->GetFieldValue($fieldname)->GetValue(); if( $email !~ /^[\w\-\.]+\@[\w\-\.]+$/){ $result = "Email address needs to be specified in email\@mycompany.com format!"; } </source> Please note that DB subscription and type properties are the same for both Group and User record types. You can check record type within the custom hook using <source lang="perl">$entity->GetEntityDefName()</source> API call. |- |CONFIG_ENABLE_CUSTOM_ACTION_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom action validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_ACTION_<ACTION_NAME> | |align="center"|No |These properties contains custom validation code. Custom validation can be written in Perl, using CQPerl API and $session and $entity global variables. Error message should be assigned to the '''$result''' variable. |- |MAX_LENGTH_FULLNAME MAX_LENGTH_PHONE MAX_LENGTH_EMAIL |align="center"| 50 |align="center"| No | Currently, ClearQuest user full name, phone and email fields are limited to 50 characters. If the limit is changed in the future releases, this property can be set to indicate the new limit. |- |} [[Category:User_Admin_Tool]] 3b33cee05783b577ca0a18002d42f864ac822c55 195 191 2013-01-19T15:38:25Z Paul 1 wikitext text/x-wiki <big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or adding customizations, such as setting field default values or adding enhanced field or action validation, without schema modification. Its configuration is stored in the ClearQuest database using udb_property records. These records are protected using Security Context feature and not visible to regular users. In addition, the most critical data is encrypted. You can find currently set property values in the public workspace query "Public Queries\Database_Settings\Properties". {| class="wikitable" cellpadding="10" ! align="left"| Property Name ! Default Value ! Secure ! Comments |- | admin_creds | |align="center"| Yes | It is a "secure" property that carries administrative user credentials in username/password format. This user account is used to communicate to the master user repository to query or sync users and groups. |- |CONFIG_LOAD_EVERYONE_GROUP |align="center"|false |align="center"|No |A built-in "Everyone" group was introduced with ClearQuest Feature Level 7. This group cannot be modified, and by default, it is not loaded to the User Administration tool. This behavior can be changed by setting this property to non-zero value. There is no reason to lad built-in "Everyone" group, but if you are using pre-FL7 database that has group with this name, it might be a solution. |- |CONFIG_MULTISITE_ENABLED |align="center"|false |align="center"|No |Enables Multisite resource-consuming validations, such as mastership of the groups that you would like to add user to. It might impact performance. Do not set it, unless you are using the tool in multisited environment and you are planning to use the tool from many sites simultaniously. |- |CONFIG_OBEY_MS_ON_CREATE |align="center"|false |align="center"|No |By default, during initial load and synchronizations, all users are loaded into the database regardless of mastership. This behavior can be changed by setting the property to non-zero value. In this case, the load will be limited to locally mastered users and groups, but it will require you to perform load from each site. |- |CONFIG_AUTO_DB_UPGRADE |align="center"|false |align="center"|No |By default, the User Admin tool operates in the same way as the standard user administration utility: you create and/or modify users and group, and then you have to execute "Upgrade_User_DBs" action to push changes into user databases. Setting this property to non-zero value would force database upgrade every time you save User or Group. Depending on size of your environment (number of users and user databases, database server, etc), there might be some performance drawbacks. If it does not work well for you, you can always switch back to the default procedure by setting this property to zero (or deleting it + logout/login). |- |CONFIG_SUPER_USER_GROUP CONFIG_USER_ADMIN_GROUP CONFIG_PASSWORD_RESET_GROUP | |align="center"|No |By default, ClearQuest user with Super User or User Admin privilege is allowed to create and update users and groups, and Super User only is allowed to delete user or group records (when no associated account exists in the master repository). It can be changed by setting the corresponding property to ClearQuest group name. Members of the group would carry the privilege withing the tool, but they would not be able to use the standard ClearQuest user administration utility (to avoid possible problems and necessity of synchronization). Members of the group set in the CONFIG_PASSWORD_RESET_GROUP are allowed to reset user's password only (execute "Password_Reset" action). |- |CONFIG_GROUP_ADMIN_SUFFIX | |align="center"|No |You can use this property to permit some users to administer specific groups only (add or remove existing users and groups). For instance, by setting this property to "_ADM", you would allow members of Some_Group_Name_ADM to administer Some_Group_Name ClearQuest group without granting them any other permissions. |- |CONFIG_GENERATE_PASSWORD |align="center"|false |align="center"|No |When this property is set to non-zero value, and you create user account with ClearQuest authentication leaving password blank, the system will generate random password and include it in the user notification (it is kept in the "NEW_USER_PASSWORD" property). |- |CONFIG_GENERATE_PASSWORD_CHARACTERS |align="center"|0-9a-zA-Z |align="center"|No |Characters used by password generator |- |CONFIG_GENERATE_PASSWORD_LENGTH |align="center"|8 |align="center"|No |Length of the generated password |- |CONFIG_USER_PROFILE_FIELDS |align="center"|UserPrivileges Groups DB_Subscription_Type DB_Subscription |align="center"|No |User account can be updated using other account as a profile. For example, you can create a user that would mirror access somebody else user account permissions. By default, the other user account User Privileges, Groups, Database subscription type and subscribed databases are copied, but it can be changed by setting CONFIG_USER_PROFILE_FIELDS property with desired set of fields in one-field-per-line format. |- |DEFAULT_USERPRIVILEGES DEFAULT_AUTHTYPE DEFAULT_DB_SUBSCRIPTION_TYPE DEFAULT_DB_SUBSCRIPTION DEFAULT_GROUPS_REQUESTED DEFAULT_PROFILE_CHOICE DEFAULT_PROFILE_OPERATION | |align="center"|No |These properties allow to configure user and group default field values. When you start creating new user, it can be initialized with LDAP authentication type, specific set of user privileges, and be subscribed to specific set of user databases. |- |CONFIG_ENABLE_CUSTOM_FIELD_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom field validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_FIELD_NAME VALIDATE_FIELD_LOGIN_NAME VALIDATE_FIELD_FULLNAME VALIDATE_FIELD_PHONE VALIDATE_FIELD_EMAIL VALIDATE_FIELD_USERPRIVILEGES VALIDATE_FIELD_PASSWORD VALIDATE_FIELD_DB_SUBSCRIPTION_TYPE VALIDATE_FIELD_DB_SUBSCRIPTION VALIDATE_FIELD_GROUPS_REQUESTED VALIDATE_FIELD_USERS VALIDATE_FIELD_GROUPS | |align="center"|No |These properties can contain custom validation hook code for User and Group record fields. There is no need to define all of them when custom validation is enabled. You can define required scripts only. The script is the same as a validation Perl hook: it can use $session and $entity global variables and entire CQPerl API. In case of validation error, '''$result''' variable needs to be set with validation error message. You can take VALIDATE_FIELD_EMAIL property as an example. It checks that user's email address was provided in correct format: <source lang="perl"> my $email = $entity->GetFieldValue($fieldname)->GetValue(); if( $email !~ /^[\w\-\.]+\@[\w\-\.]+$/){ $result = "Email address needs to be specified in email\@mycompany.com format!"; } </source> Please note that DB subscription and type properties are the same for both Group and User record types. You can check record type within the custom hook using <source lang="perl">$entity->GetEntityDefName()</source> API call. |- |CONFIG_ENABLE_CUSTOM_ACTION_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom action validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_ACTION_<ACTION_NAME> | |align="center"|No |These properties contains custom validation code. Custom validation can be written in Perl, using CQPerl API and $session and $entity global variables. Error message should be assigned to the '''$result''' variable. |- |MAX_LENGTH_FULLNAME MAX_LENGTH_PHONE MAX_LENGTH_EMAIL |align="center"| 50 |align="center"| No | Currently, ClearQuest user full name, phone and email fields are limited to 50 characters. If the limit is changed in the future releases, this property can be set to indicate the new limit. |- |} [[Category:User_Admin_Tool]] 9e953cc88f1f91a54e05cbbc994ed205f0e32538 197 195 2013-01-20T21:17:06Z Paul 1 wikitext text/x-wiki <big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or adding customizations, such as setting field default values or adding enhanced field or action validation, without schema modification. Its configuration is stored in the ClearQuest database using udb_property records. These records are protected using Security Context feature and not visible to regular users. In addition, the most critical data is encrypted. You can find currently set property values in the public workspace query "Public Queries\Database_Settings\Properties". {| class="wikitable" cellpadding="10" ! align="left"| Property Name ! Default Value ! Secure ! Comments |- | CONFIG_ADMIN_CREDS | |align="center"| Yes | It is a "secure" property that carries administrative user credentials in username/password format. This user account is used to communicate to the master user repository to query or sync users and groups. |- |CONFIG_AUTO_DB_UPGRADE |align="center"|false |align="center"|No |By default, the User Admin tool operates in the same way as the standard user administration utility: you create and/or modify users and group, and then you have to execute "Upgrade_User_DBs" action to push changes into user databases. Setting this property to non-zero value would force database upgrade every time you save User or Group. Depending on size of your environment (number of users and user databases, database server, etc), there might be some performance drawbacks. If it does not work well for you, you can always switch back to the default procedure by setting this property to zero (or deleting it + logout/login). |- |CONFIG_LOAD_EVERYONE_GROUP |align="center"|false |align="center"|No |A built-in "Everyone" group was introduced with ClearQuest Feature Level 7. This group cannot be modified, and by default, it is not loaded to the User Administration tool. This behavior can be changed by setting this property to non-zero value. There is no reason to lad built-in "Everyone" group, but if you are using pre-FL7 database that has group with this name, it might be a solution. |- |CONFIG_MULTISITE_ENABLED |align="center"|false |align="center"|No |Enables Multisite resource-consuming validations, such as mastership of the groups that you would like to add user to. It might impact performance. Do not set it, unless you are using the tool in multisited environment and you are planning to use the tool from many sites simultaniously. |- |CONFIG_OBEY_MS_ON_CREATE |align="center"|false |align="center"|No |By default, during initial load and synchronizations, all users are loaded into the database regardless of mastership. This behavior can be changed by setting the property to non-zero value. In this case, the load will be limited to locally mastered users and groups, but it will require you to perform load from each site. |- |CONFIG_SUPER_USER_GROUP CONFIG_USER_ADMIN_GROUP CONFIG_PASSWORD_RESET_GROUP | |align="center"|No |By default, ClearQuest user with Super User or User Admin privilege is allowed to create and update users and groups, and Super User only is allowed to delete user or group records (when no associated account exists in the master repository). It can be changed by setting the corresponding property to ClearQuest group name. Members of the group would carry the privilege withing the tool, but they would not be able to use the standard ClearQuest user administration utility (to avoid possible problems and necessity of synchronization). Members of the group set in the CONFIG_PASSWORD_RESET_GROUP are allowed to reset user's password only (execute "Password_Reset" action). |- |CONFIG_GROUP_ADMIN_SUFFIX | |align="center"|No |You can use this property to permit some users to administer specific groups only (add or remove existing users and groups). For instance, by setting this property to "_ADM", you would allow members of Some_Group_Name_ADM to administer Some_Group_Name ClearQuest group without granting them any other permissions. |- |CONFIG_GENERATE_PASSWORD |align="center"|false |align="center"|No |When this property is set to non-zero value, and you create user account with ClearQuest authentication leaving password blank, the system will generate random password and include it in the user notification (it is kept in the "NEW_USER_PASSWORD" property). |- |CONFIG_GENERATE_PASSWORD_CHARACTERS |align="center"|0-9a-zA-Z |align="center"|No |Characters used by password generator |- |CONFIG_GENERATE_PASSWORD_LENGTH |align="center"|8 |align="center"|No |Length of the generated password |- |CONFIG_USER_PROFILE_FIELDS |align="center"|UserPrivileges Groups DB_Subscription_Type DB_Subscription |align="center"|No |User account can be updated using other account as a profile. For example, you can create a user that would mirror access somebody else user account permissions. By default, the other user account User Privileges, Groups, Database subscription type and subscribed databases are copied, but it can be changed by setting CONFIG_USER_PROFILE_FIELDS property with desired set of fields in one-field-per-line format. |- |DEFAULT_USERPRIVILEGES DEFAULT_AUTHTYPE DEFAULT_DB_SUBSCRIPTION_TYPE DEFAULT_DB_SUBSCRIPTION DEFAULT_GROUPS_REQUESTED DEFAULT_PROFILE_CHOICE DEFAULT_PROFILE_OPERATION | |align="center"|No |These properties allow to configure user and group default field values. When you start creating new user, it can be initialized with LDAP authentication type, specific set of user privileges, and be subscribed to specific set of user databases. |- |CONFIG_ENABLE_CUSTOM_FIELD_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom field validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_FIELD_NAME VALIDATE_FIELD_LOGIN_NAME VALIDATE_FIELD_FULLNAME VALIDATE_FIELD_PHONE VALIDATE_FIELD_EMAIL VALIDATE_FIELD_USERPRIVILEGES VALIDATE_FIELD_PASSWORD VALIDATE_FIELD_DB_SUBSCRIPTION_TYPE VALIDATE_FIELD_DB_SUBSCRIPTION VALIDATE_FIELD_GROUPS_REQUESTED VALIDATE_FIELD_USERS VALIDATE_FIELD_GROUPS | |align="center"|No |These properties can contain custom validation hook code for User and Group record fields. There is no need to define all of them when custom validation is enabled. You can define required scripts only. The script is the same as a validation Perl hook: it can use $session and $entity global variables and entire CQPerl API. In case of validation error, '''$result''' variable needs to be set with validation error message. You can take VALIDATE_FIELD_EMAIL property as an example. It checks that user's email address was provided in correct format: <source lang="perl"> my $email = $entity->GetFieldValue($fieldname)->GetValue(); if( $email !~ /^[\w\-\.]+\@[\w\-\.]+$/){ $result = "Email address needs to be specified in email\@mycompany.com format!"; } </source> Please note that DB subscription and type properties are the same for both Group and User record types. You can check record type within the custom hook using <source lang="perl">$entity->GetEntityDefName()</source> API call. |- |CONFIG_ENABLE_CUSTOM_ACTION_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom action validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_ACTION_<ACTION_NAME> | |align="center"|No |These properties contains custom validation code. Custom validation can be written in Perl, using CQPerl API and $session and $entity global variables. Error message should be assigned to the '''$result''' variable. |- |MAX_LENGTH_FULLNAME MAX_LENGTH_PHONE MAX_LENGTH_EMAIL |align="center"| 50 |align="center"| No | Currently, ClearQuest user full name, phone and email fields are limited to 50 characters. If the limit is changed in the future releases, this property can be set to indicate the new limit. |- |} [[Category:User_Admin_Tool]] f787b1135b17ed9b8b86bc9776eac94d8bafd3a8 14 71 192 2013-01-19T00:08:21Z Paul 1 Created page with "User Administration Tool for IBM-Rational ClearQuest" wikitext text/x-wiki User Administration Tool for IBM-Rational ClearQuest 6e7c08e0daedb558b206ab43e261c0474d17dac1 6 72 199 2013-01-21T20:56:42Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 73 200 2013-01-21T21:00:14Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 74 201 2013-01-21T21:07:08Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 75 202 2013-01-21T21:11:38Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 76 203 2013-01-21T21:17:39Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 77 204 2013-01-21T21:26:58Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 78 205 2013-01-21T21:44:57Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 79 206 2013-01-21T21:50:31Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 80 207 2013-01-21T21:55:51Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 81 208 2013-01-21T21:59:42Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 82 209 2013-01-21T22:05:37Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 83 210 2013-01-21T22:08:11Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 84 211 2013-01-21T22:10:05Z Paul 1 Created page with "<big>'''Managing GlearQuest Users and Groups'''</big> The User Administration tool is a ClearQuest database, and in order to start managing users you need to login to the dat..." wikitext text/x-wiki <big>'''Managing GlearQuest Users and Groups'''</big> The User Administration tool is a ClearQuest database, and in order to start managing users you need to login to the database you created during the installation. Initially, only ClearQuest users with Super User or User Admin privileges are allowed to manage users and groups, but it can be changed. Please check [[User_Admin_Tool_Configuration | User Administration Tool Configuration]] page for details. [[File:cqua_login.png|none]] <br /><br /> == Adding a User == Click on '''New->User''' in the drop down list on the left. [[File:cqua_new_user_1.png|none]] <br /> New user form will be opened for editing. Fill in the user information * Login * Password (In case of ClearQuest authentication, if left blank, a random password can be generated by setting CONFIG_GENERATE_PASSWORD property) * Full Name * Email address * Phone * Miscellaneous information (description) [[File:cqua_user_lists.png|none]] <br /> In order to change user privileges (1), subscribed user databases (2), or user group membership (3), click on "Edit" pictogram right to correspondent field. Please note that the list of databases can be updated when database subscription is set to "Selected Databases" only. When you selecting a group from the list, you can limit choices by typing partial name of the group.<br /> [[File:cqua_user_groups.png|none]] <br /> Select groups from the list and click "Add" to move them to the selection box. When you are satisfied with the selection, click "OK" button to close the Edit List form. <br />When you finished editing new user, click "Save" button on the form to save changes. After the user form is closed you can re-open it for review from "Recent Items" list on the left side of the workspace. Email notification will be sent to the user providing details on the account, initial password (for ClearQuest authentication), and CQWeb URL.<br /> [[File:User_admin_email_notification_1.png|none]] <br /> == Changing a User == Find the user using Query in the Public Workspace and select it. The system will open the user form. Select action "Update" to start changing user information. [[File:cqua_update_user.png|none]] <br /> Change user information and click on the "Save" button to apply changes. The user will receive a email notification describing the change. [[File:User_admin_email_notification_2.png|none]] <br /> == Adding ClearQuest Group == Select '''New->Group''' from the drop-down menu on the left side of the workspace. New Group form will be opened for editing. [[File:cqua_new_group.png|none]] Add Group members by clicking on "Add" button (1), and selecting groups from the list. You can search groups by name or by using any query from the ClearQuest workspace. Select groups to add and click "OK" to close the "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group.png|none]] <br /> In order to add users to the group, click on "Add" button (1) right to the Users field. It will open "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group_2.png|none]] <br /> You can search users by login name (or partial login name) in the selection dialog (1), or click on "Browse" button (2) and use queries from the workspace for advanced search capabilities <br /> [[File:cqua_add_users_to_group_3.png|none]] <br /> When you finished editing group, click on "Save" button to commit changes. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 9f3c0c28972fb2a7ca90facf3c36d07f2bd5977e 216 211 2013-01-21T23:45:00Z Paul 1 wikitext text/x-wiki <big>'''Managing GlearQuest Users and Groups'''</big> __TOC__ The User Administration tool is a ClearQuest database, and in order to start managing users you need to login to the database you created during the installation. Initially, only ClearQuest users with Super User or User Admin privileges are allowed to manage users and groups, but it can be changed. Please check [[User_Admin_Tool_Configuration | User Administration Tool Configuration]] page for details. [[File:cqua_login.png|none]] <br /><br /> == Adding a User == Click on '''New->User''' in the drop down list on the left. [[File:cqua_new_user_1.png|none]] <br /> New user form will be opened for editing. Fill in the user information * Login * Password (In case of ClearQuest authentication, if left blank, a random password can be generated by setting CONFIG_GENERATE_PASSWORD property) * Full Name * Email address * Phone * Miscellaneous information (description) [[File:cqua_user_lists.png|none]] <br /> In order to change user privileges (1), subscribed user databases (2), or user group membership (3), click on "Edit" pictogram right to correspondent field. Please note that the list of databases can be updated when database subscription is set to "Selected Databases" only. When you selecting a group from the list, you can limit choices by typing partial name of the group.<br /> [[File:cqua_user_groups.png|none]] <br /> Select groups from the list and click "Add" to move them to the selection box. When you are satisfied with the selection, click "OK" button to close the Edit List form. <br />When you finished editing new user, click "Save" button on the form to save changes. After the user form is closed you can re-open it for review from "Recent Items" list on the left side of the workspace. Email notification will be sent to the user providing details on the account, initial password (for ClearQuest authentication), and CQWeb URL.<br /> [[File:User_admin_email_notification_1.png|none]] <br /> == Changing a User == Find the user using Query in the Public Workspace and select it. The system will open the user form. Select action "Update" to start changing user information. [[File:cqua_update_user.png|none]] <br /> Change user information and click on the "Save" button to apply changes. The user will receive a email notification describing the change. [[File:User_admin_email_notification_2.png|none]] <br /> == Using User Profiles to Add or Update User == One of the regular tasks that hard to perform using the standard user administration tool is to "create use like some other user". In Enterprise environment with thousands of users and hundreds of groups it is quite a challenging task. The user admin tool offers you a very simple way to achieve the goal.<br /> Start creating new user or updating existing user account, and select '''Profiling and Options''' tab on the user form.<br /> [[File:cqua_profile_1.png|none]] <br /> Select profile operation: you can mirror current user as other account (Replace) or add permissions of the other user account (Add). <br /> [[File:cqua_profile_2.png|none]] <br /> Select choice list option: it can be one of following * '''None''' - profile choice list is not populated, and you can type in profile login directly. * '''Templates''' - profile choices are limited to the users with "Template" attribute set. It can be regular user accounts, or specially created profiles, such as "CM Manager", "Team Lead", etc. Template users could be specially created as inactive, and in this case they would not be propagated to the user databases. * '''All Users''' - profile choice list is populated with all active user accounts. <br /> [[File:cqua_profile_3.png|none]] <br /> While selecting profile user, you can start typing user name and it will automatically filter the choice list. After profile user is selected, list view below is populated with profile user details: full name, email, phone number. You can double click on the user record to open User form with additional details. <br /> [[File:cqua_profile_4.png|none]] <br /> When user is validated, click on the "Update User as Request" button to perform profiling operation. By default, it will mirror or copy profile User Privileges, Groups, Database subscription type and list of databases the user is subscribed to. This bevaviour can be changed by setting CONFIG_USER_PROFILE_FIELDS property to set of fields that need to be used. For example, you can limit profile operation to user groups, or user groups and privileges.<br /> When you finished editing user account, click on Save button to commit changes to the database. <br /> == Adding ClearQuest Group == Select '''New->Group''' from the drop-down menu on the left side of the workspace. New Group form will be opened for editing. [[File:cqua_new_group.png|none]] Add Group members by clicking on "Add" button (1), and selecting groups from the list. You can search groups by name or by using any query from the ClearQuest workspace. Select groups to add and click "OK" to close the "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group.png|none]] <br /> In order to add users to the group, click on "Add" button (1) right to the Users field. It will open "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group_2.png|none]] <br /> You can search users by login name (or partial login name) in the selection dialog (1), or click on "Browse" button (2) and use queries from the workspace for advanced search capabilities <br /> [[File:cqua_add_users_to_group_3.png|none]] <br /> When you finished editing group, click on "Save" button to commit changes. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 473eea9bfc4f5507ba63004a7b2890978381ba44 217 216 2013-01-22T00:39:02Z Paul 1 wikitext text/x-wiki <big>'''Managing GlearQuest Users and Groups'''</big> __TOC__ The User Administration tool is a ClearQuest database, and in order to start managing users you need to login to the database you created during the installation. Initially, only ClearQuest users with Super User or User Admin privileges are allowed to manage users and groups, but it can be changed. Please check [[User_Admin_Tool_Configuration | User Administration Tool Configuration]] page for details. [[File:cqua_login.png|none]] <br /><br /> == Adding a User == Click on '''New->User''' in the drop down list on the left. [[File:cqua_new_user_1.png|none]] <br /> New user form will be opened for editing. Fill in the user information * Login * Password (In case of ClearQuest authentication, if left blank, a random password can be generated by setting CONFIG_GENERATE_PASSWORD property) * Full Name * Email address * Phone * Miscellaneous information (description) [[File:cqua_user_lists.png|none]] <br /> In order to change user privileges (1), subscribed user databases (2), or user group membership (3), click on "Edit" pictogram right to correspondent field. Please note that the list of databases can be updated when database subscription is set to "Selected Databases" only. When you selecting a group from the list, you can limit choices by typing partial name of the group.<br /> [[File:cqua_user_groups.png|none]] <br /> Select groups from the list and click "Add" to move them to the selection box. When you are satisfied with the selection, click "OK" button to close the Edit List form. <br />When you finished editing new user, click "Save" button on the form to save changes. After the user form is closed you can re-open it for review from "Recent Items" list on the left side of the workspace. Email notification will be sent to the user providing details on the account, initial password (for ClearQuest authentication), and CQWeb URL.<br /> [[File:User_admin_email_notification_1.png|none]] <br /> == Changing a User == Find the user using Query in the Public Workspace and select it. The system will open the user form. Select action "Update" to start changing user information. [[File:cqua_update_user.png|none]] <br /> Change user information and click on the "Save" button to apply changes. The user will receive a email notification describing the change. [[File:User_admin_email_notification_2.png|none]] <br /> == Using User Profiles to Add or Update User == One of the regular tasks that hard to perform using the standard user administration tool is to "create use like some other user". In Enterprise environment with thousands of users and hundreds of groups it is quite a challenging task. The user admin tool offers you a very simple way to achieve the goal.<br /> Start creating new user or updating existing user account, and select '''Profiling and Options''' tab on the user form.<br /> [[File:cqua_profile_1.png|none]] <br /> Select profile operation: you can mirror current user as other account (Replace) or add permissions of the other user account (Add). <br /> [[File:cqua_profile_2.png|none]] <br /> Select choice list option: it can be one of following * '''None''' - profile choice list is not populated, and you can type in profile login directly. * '''Templates''' - profile choices are limited to the users with "Template" attribute set. It can be regular user accounts, or specially created profiles, such as "CM Manager", "Team Lead", etc. Template users could be specially created as inactive, and in this case they would not be propagated to the user databases. * '''All Users''' - profile choice list is populated with all active user accounts. <br /> [[File:cqua_profile_3.png|none]] <br /> While selecting profile user, you can start typing user name and it will automatically filter the choice list. After profile user is selected, list view below is populated with profile user details: full name, email, phone number. You can double click on the user record to open User form with additional details. <br /> [[File:cqua_profile_4.png|none]] <br /> When user is validated, click on the "Update User as Request" button to perform profiling operation. By default, it will mirror or copy profile User Privileges, Groups, Database subscription type and list of databases the user is subscribed to. This bevaviour can be changed by setting CONFIG_USER_PROFILE_FIELDS property to set of fields that need to be used. For example, you can limit profile operation to user groups, or user groups and privileges.<br /> When you finished editing user account, click on Save button to commit changes to the database. <br /> == Adding ClearQuest Group == Select '''New->Group''' from the drop-down menu on the left side of the workspace. New Group form will be opened for editing. [[File:cqua_new_group.png|none]] Add Group members by clicking on "Add" button (1), and selecting groups from the list. You can search groups by name or by using any query from the ClearQuest workspace. Select groups to add and click "OK" to close the "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group.png|none]] <br /> In order to add users to the group, click on "Add" button (1) right to the Users field. It will open "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group_2.png|none]] <br /> You can search users by login name (or partial login name) in the selection dialog (1), or click on "Browse" button (2) and use queries from the workspace for advanced search capabilities <br /> [[File:cqua_add_users_to_group_3.png|none]] <br /> When you finished editing group, click on "Save" button to commit changes. <br /> == Upgrading User Databases == In the same way as with the standard user administration tool, you need to upgrade user databases to push master user and group changes from the master repository into user databases. User Administration tool offers you more than one way to do it. * '''Push User To User DBs''' action, available for user accounts only. It is an extremely lightweght operation that push current user data to the subscribed databases, but does not touch any other pending changes, or update user references. For instance, it would not update group membership changes, but if you need to push new user password on extremely large database with many pending changes, it might be helpful. * '''Upgrade User DBs''' action, available for User and Groups. It is an equivalent of the user database upgrade from the standard user administration tool. * '''Automatic Upgrade''' can be enabled by setting CONFIG_AUTO_DB_UPGRADE property to non-zero value. In this case database upgrade is executed automatically every time you commit User or Group changes to the database. It would be a recommended way, unless you see serious performance degradation. I did not see any issues in the environment with limited number of user databases and few thousands of users, but it is possible. == Other Special Actions == {| class="wikitable" cellpadding="10" ! align="left"| Action Name ! Entity ! Permissions ! Comments |- |Save To Master |align="center"| User, Group |align="center"| Super User or User Admin |Saves all fields from the current record to the master repository |- |Refresh From Master |align="center"| User, Group |align="center"| Super User or User Admin |Loads all fields from the master repository to the current record |- |Save All To Master |align="center"| User, Group |align="center"| Super User |This action saves all Users and Groups from the User Administration Tool to the master repository |- |Load All From Master |align="center"| User, Group |align="center"| Super User |Loads all Users and Groups from the master repository into the user administration tool. |- |Password Reset |align="center"| User |align="center"| Super User, User Admin, or Password Admin |For user with ClearQuest authentication, it generates new password and sends it directly to the user. No database upgrade is required. |- |} <br /> == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] dfd311eef6b489f1f09a0ef943920aa559cf9339 234 217 2013-02-01T14:40:40Z Paul 1 wikitext text/x-wiki <big>'''Managing GlearQuest Users and Groups'''</big> __TOC__ The User Administration tool is a ClearQuest database, and in order to start managing users you need to login to the database you created during the installation. Initially, only ClearQuest users with Super User or User Admin privileges are allowed to manage users and groups, but it can be changed. Please check [[User_Admin_Tool_Configuration | User Administration Tool Configuration]] page for details. [[File:cqua_login.png|none]] <br /><br /> == Adding a User == Click on '''New->User''' in the drop down list on the left. [[File:cqua_new_user_1.png|none]] <br /> New user form will be opened for editing. Fill in the user information * Login * Password (In case of ClearQuest authentication, if left blank, a random password can be generated by setting CONFIG_GENERATE_PASSWORD property) * Full Name * Email address * Phone * Miscellaneous information (description) [[File:cqua_user_lists.png|none]] <br /> In order to change user privileges (1), subscribed user databases (2), or user group membership (3), click on "Edit" pictogram right to correspondent field. Please note that the list of databases can be updated when database subscription is set to "Selected Databases" only. When you selecting a group from the list, you can limit choices by typing partial name of the group.<br /> [[File:cqua_user_groups.png|none]] <br /> Select groups from the list and click "Add" to move them to the selection box. When you are satisfied with the selection, click "OK" button to close the Edit List form. <br />When you finished editing new user, click "Save" button on the form to save changes. After the user form is closed you can re-open it for review from "Recent Items" list on the left side of the workspace. Email notification will be sent to the user providing details on the account, initial password (for ClearQuest authentication), and CQWeb URL.<br /> [[File:User_admin_email_notification_1.png|none]] <br /> == Changing a User == Find the user using Query in the Public Workspace and select it. The system will open the user form. Select action "Update" to start changing user information. [[File:cqua_update_user.png|none]] <br /> Change user information and click on the "Save" button to apply changes. The user will receive a email notification describing the change. [[File:User_admin_email_notification_2.png|none]] <br /> == Using User Profiles to Add or Update User == One of the regular tasks that hard to perform using the standard user administration tool is to "create use like some other user". In Enterprise environment with thousands of users and hundreds of groups it is quite a challenging task. The user admin tool offers you a very simple way to achieve the goal.<br /> Start creating new user or updating existing user account, and select '''Profiling and Options''' tab on the user form.<br /> [[File:cqua_profile_1.png|none]] <br /> Select profile operation: you can mirror current user as other account (Replace) or add permissions of the other user account (Add). <br /> [[File:cqua_profile_2.png|none]] <br /> Select choice list option: it can be one of following * '''None''' - profile choice list is not populated, and you can type in profile login directly. * '''Templates''' - profile choices are limited to the users with "Template" attribute set. It can be regular user accounts, or specially created profiles, such as "CM Manager", "Team Lead", etc. Template users could be specially created as inactive, and in this case they would not be propagated to the user databases. * '''All Users''' - profile choice list is populated with all active user accounts. <br /> [[File:cqua_profile_3.png|none]] <br /> While selecting profile user, you can start typing user name and it will automatically filter the choice list. After profile user is selected, list view below is populated with profile user details: full name, email, phone number. You can double click on the user record to open User form with additional details. <br /> [[File:cqua_profile_4.png|none]] <br /> When user is validated, click on the "Update User as Request" button to perform profiling operation. By default, it will mirror or copy profile User Privileges, Groups, Database subscription type and list of databases the user is subscribed to. This bevaviour can be changed by setting CONFIG_USER_PROFILE_FIELDS property to set of fields that need to be used. For example, you can limit profile operation to user groups, or user groups and privileges.<br /> When you finished editing user account, click on Save button to commit changes to the database. <br /> == Adding ClearQuest Group == Select '''New->Group''' from the drop-down menu on the left side of the workspace. New Group form will be opened for editing. [[File:cqua_new_group.png|none]] Add Group members by clicking on "Add" button (1), and selecting groups from the list. You can search groups by name or by using any query from the ClearQuest workspace. Select groups to add and click "OK" to close the "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group.png|none]] <br /> In order to add users to the group, click on "Add" button (1) right to the Users field. It will open "Search and Select Records" dialog. <br /> [[File:cqua_add_users_to_group_2.png|none]] <br /> You can search users by login name (or partial login name) in the selection dialog (1), or click on "Browse" button (2) and use queries from the workspace for advanced search capabilities <br /> [[File:cqua_add_users_to_group_3.png|none]] <br /> When you finished editing group, click on "Save" button to commit changes. <br /> == Upgrading User Databases == In the same way as with the standard user administration tool, you need to upgrade user databases to push master user and group changes from the master repository into user databases. User Administration tool offers you more than one way to do it. * '''Push User To User DBs''' action, available for user accounts only. It is an extremely lightweght operation that push current user data to the subscribed databases, but does not touch any other pending changes, or update user references. For instance, it would not update group membership changes, but if you need to push new user password on extremely large database with many pending changes, it might be helpful. * '''Upgrade User DBs''' action, available for User and Groups. It is an equivalent of the user database upgrade from the standard user administration tool. * '''Automatic Upgrade''' can be enabled by setting CONFIG_AUTO_DB_UPGRADE property to non-zero value. In this case database upgrade is executed automatically every time you commit User or Group changes to the database. It would be a recommended way, unless you see serious performance degradation. I did not see any issues in the environment with limited number of user databases and few thousands of users, but it is possible. == Other Special Actions == {| class="wikitable" cellpadding="10" ! align="left"| Action Name ! Entity ! Permissions ! Comments |- |Save To Master |align="center"| User, Group |align="center"| Super User or User Admin |Saves all fields from the current record to the master repository |- |Refresh From Master |align="center"| User, Group |align="center"| Super User or User Admin |Loads all fields from the master repository to the current record |- |Save All To Master |align="center"| User, Group |align="center"| Super User |This action saves all Users and Groups from the User Administration Tool to the master repository |- |Load All From Master |align="center"| User, Group |align="center"| Super User |Loads all Users and Groups from the master repository into the user administration tool. |- |Password Reset |align="center"| User |align="center"| Super User, User Admin, or Password Admin |For user with ClearQuest authentication, it generates new password and sends it directly to the user. No database upgrade is required. |- |} <br /> == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:User_Admin_Tool]] d7f75e2e3a5f5400194f69fd89a1a57fe2afe5e3 6 85 212 2013-01-21T23:15:53Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 86 213 2013-01-21T23:23:29Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 87 214 2013-01-21T23:24:21Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 6 88 215 2013-01-21T23:35:56Z Paul 1 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 0 89 218 2013-01-22T03:29:44Z Paul 1 Created page with "<big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It b..." wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles, that can used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capabilities. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [ClearQuest_Email_Notification_Package | Email Notification package], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [ClearQuest_Email_Notification_Package | Email Notification package] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 6cc2720da45cd4c76a1a82e3e2c07967929abf0e 219 218 2013-01-22T03:31:15Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles, that can used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capabilities. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] d8a41ef30725c343d69390b336b61618c2bba130 226 219 2013-01-23T19:47:24Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles, that can used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capabilities. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 7da68f745c2c4f4d68e0151cd9ae7cb1dfa491f6 227 226 2013-01-24T01:12:53Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:User_Admin_Tool]] 253790dbe8f282ea67d77f72dd6b76ecb0a1e172 250 227 2013-02-01T14:47:20Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:User_Admin_Tool]] a604ec86122232e3003661e80d0da1736c59cef1 0 2 220 196 2013-01-22T13:35:02Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and add other valuable features, such as ultimate query and search capabilities, customizable deefaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] f8bded072af4aea832260f657d3757b00e9b20f0 221 220 2013-01-22T14:48:52Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and add other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /><br /> [[Category:Rational]] 72fd9c225b42abb0e2478f16642cad8d5cfb7229 222 221 2013-01-22T15:31:34Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and add other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 8048a4035107dfe43ecb88bfc7c784d9c035cb11 224 222 2013-01-23T18:30:57Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and adds other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] e06ec0ea0cff9c0363bc652bc5cd3e7c2493895f 228 224 2013-01-28T23:56:15Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and adds other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 3d9c62699b33472dd03042e23e06444d34f6b8fa 0 45 223 162 2013-01-22T23:05:48Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically. == Installation Instruction == '''Please create a backup of schema and user databases before the installation.'''<br /> The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Automatic Install === * Unpack the distribution to your local or network drive (you cannot start the installation from a network share using UNC path) * Launch "install.bat" in the root of the distribution * Accept license agreement * Provide administrative user credentials, ClearQuest connection, database name, and click on "Connect" When installation is completed, login to the user database and run "Public Queries/Administration/Dynamic_Lists" query to verify Dynamic list data. You can start using the tool immediately. === Manual Install === If you prefer to install the Editor manually, please follow the steps below It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save the downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database. * Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted. * Import integration using the "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that the schema update was imported and no issues were detected. [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database). [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit a new record of the "Dynamic_List" type: [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names from the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list values will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit the record to the database ==== Creating Dynamic List Administration Query ==== Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no error occurred, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with their proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Administering Dynamic Lists == When all the Dynamic_List records are populated, List Administrators can start using the query you created and Dynamic_Lists records to modify the content of the linked dynamic lists. Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves the content of the current ClearQuest records into a correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source. |- | SyncAllLists | Utilities / Script | Super User | This action syncs ClearQuest records with their correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 3f874025833ab234506e19699bcafdc5c9bedaa6 245 223 2013-02-01T14:45:27Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically. == Installation Instruction == '''Please create a backup of schema and user databases before the installation.'''<br /> The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Automatic Install === * Unpack the distribution to your local or network drive (you cannot start the installation from a network share using UNC path) * Launch "install.bat" in the root of the distribution * Accept license agreement * Provide administrative user credentials, ClearQuest connection, database name, and click on "Connect" When installation is completed, login to the user database and run "Public Queries/Administration/Dynamic_Lists" query to verify Dynamic list data. You can start using the tool immediately. === Manual Install === If you prefer to install the Editor manually, please follow the steps below It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Download and Unpack Schema Integration ==== Save the downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database. * Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted. * Import integration using the "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that the schema update was imported and no issues were detected. [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database). [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit a new record of the "Dynamic_List" type: [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names from the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list values will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit the record to the database ==== Creating Dynamic List Administration Query ==== Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no error occurred, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with their proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Administering Dynamic Lists == When all the Dynamic_List records are populated, List Administrators can start using the query you created and Dynamic_Lists records to modify the content of the linked dynamic lists. Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves the content of the current ClearQuest records into a correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source. |- | SyncAllLists | Utilities / Script | Super User | This action syncs ClearQuest records with their correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] fe71d71f02986215495ffaf5308a81f0dfcb5e31 0 6 225 178 2013-01-23T19:46:18Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://store.cqadmin.com/index.php/dynamic-list-editor-for-ibm-rational-clearquest.html CQAdmin store]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [http://store.cqadmin.com/index.php/clearquest/user-administration-tool.html CQAdmin store]. <br /> == Download Instructions == === Download Links in Email === In order to download products, you have to register at [http://store.cqadmin.com/index.php/ CQAdmin store] and place your order. In few minutes you will receive a confirmation email containing download links. [[File:email_links.png]] === Downloading Products from the Store === Alternatively, you could use "My Downloadable Products" section of your account. You would need to click on the download link right to the order title. [[File:store_links.png]] === '''Microsoft Internet Explorer''' users === '''Microsoft Internet Explorer''' users might need to use "Save As" option to download file correctly: * Right click on the download link * Select "Save As" option from the context menu * Save downloaded file as "some_name.zip" [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] 577913becc99e35f3710135209132dbc3c9ef9f4 247 225 2013-02-01T14:46:22Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://store.cqadmin.com/index.php/clearquest/cq-email-notification.html CQAdmin store] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://store.cqadmin.com/index.php/dynamic-list-editor-for-ibm-rational-clearquest.html CQAdmin store]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [http://store.cqadmin.com/index.php/clearquest/user-administration-tool.html CQAdmin store]. <br /> == Download Instructions == === Download Links in Email === In order to download products, you have to register at [http://store.cqadmin.com/index.php/ CQAdmin store] and place your order. In few minutes you will receive a confirmation email containing download links. [[File:email_links.png]] === Downloading Products from the Store === Alternatively, you could use "My Downloadable Products" section of your account. You would need to click on the download link right to the order title. [[File:store_links.png]] === '''Microsoft Internet Explorer''' users === '''Microsoft Internet Explorer''' users might need to use "Save As" option to download file correctly: * Right click on the download link * Select "Save As" option from the context menu * Save downloaded file as "some_name.zip" [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] b14dcdaca8df38bb49b38f2a8189134e317374f1 0 9 229 17 2013-02-01T14:38:50Z Paul 1 wikitext text/x-wiki =Applying Package to a Stateless record type= You cannot apply any package to stateless record type using Package Wizard. Fortunately, command line tool ''packageutil'' does not have such restrictions * Apply package to stateless record type from command line <source lang="bash"> packageutil enablerecord -dbset <connection> <login> <admin> \ <schema_name> EmailNotification <record_type> -nocheckin </source> --- Modifying work in progress on revisiioon xxx of schema 'Your_Schema_Name' +++ Enabled record type 'record_type' for version '1.2' of package 'EmailNotification' --- Saved work in progress on revision 22 of schema 'Your_Schema_Name' * Open schema in designer to verify changes. * Checkin schema and upgrade user databases. '''Note:''' Any action of Base type cause a delay in stateless record type actions (even simple one). The delay can be significant if you have hundreds of thousands records and need to import them on regular basis. All operations seems to be about 7 times slower (with BASE actions vs without it). [[Category:Rational]] [[Category:Email_Notification_Package]] d98809fa623d8c317d430d055e53b1731554b21e 0 5 230 182 2013-02-01T14:39:20Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> [[File:R4_Rational.jpg|right|140px]] Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Support == : ClearQuest Email Notification package is [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html officially supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 8ec9b8b23f870f6f06813f945efa3215c9193783 0 11 231 21 2013-02-01T14:39:43Z Paul 1 wikitext text/x-wiki ==Why the package was created?== I was not satisfied with the functionality provided by the standard solution. Let me give you a brief overview of ther features that we (do not) have in the standard package distributed with ClearQuest. == Top three ''features'' of the standard package that I do NOT like== === Inflexibility === Notification configuration is limited to selection of fields that are included in the message. Can you create custom subject with pre-configured text, or provide detailed instructions on why he or she received the notification and what needs to be done? Yes, you can, but you would need to create a field with solely purpose: to keep the text to be included in the message. I do not think that it is a great idea to extend data structure with a bunch of unnecessary fields. === Unreliability === If notification is not sent due to mail service unavailability, client’s misconfiguration, antivirus block, or any other reason – it is lost. You will never be able to find why it was not delivered. === Terrible configuration === Notification settings need to be configured on every single client. It is not too bad when you use CQWeb only, but imagine what it cost you when you have thousand of fat clients installed. How simple would it be to change settings, for example, smtp host? When you enabled notification on a client, it is enabled for all databases accessed from the client. It does not matter, whether it is a test or production database – it makes it very complicated to develop and test notification rules. Finally, a user could simply turn off email notification on his or her machine, and you can do nothing about it. Personally, I do not understand why the vendor of so powerful tool as ClearQuest cannot offer something better for their customers.<br /><br /> ==What options do we have?== You know all disadvantages above even better than me. I do not use standard package for years now. You might be frustrated, but what are the options do you have? * You can continue using standard package and simply decline any enhancements requested by your customers, since they cannot be implemented. The advantage is that you have supported solution. Unfortunately, it is the only advantage. * Another option could be to develop your own, custom made, notification hook. (You might be already have one?) The benefit is that it is your own solution, but do you need to update ClearQuest schema and upgrade user databases when any change is required? Is it easy to deploy it to a new schema? Is it easy to support in multiple schemas? I think, you know it better. * Fortunately, there is one more option that you can try: an alternative [[ClearQuest_Email_Notification_Package | Email Notification package]]. <br /><br /> [[Category:Rational]] [[Category:Email_Notification_Package]] 15a0963b155fbb16f51dad2bdd45bc7fb64bdabf 0 38 232 65 2013-02-01T14:40:02Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <big>'''Creating first notification rule'''</big> == Minimum configuration == Detailed package configuration instructions can be found [[Package_configuration | here]] At least two database propertied must be defined to start using the package: # '''email_host''' - SMTP relay name, the host that will accept generated emails for delivery # '''email_enabled''' - should be set to 1 to enable email notifications Open ClearQuest and configure package according to package configuration instructions submit properties (udb_property records): [[Image:submit_properties.jpg | none ]] === Set mail_host = your SMTP host === [[Image:email_host.jpg]] === Set email_enabled = 1 === Second mandatory property besides mail_host. Notifications will not be generated is the property is not set! Submit udb_property record, set name to '''email_enabled''' and value '''1''', click OK to commit property to the database. === Set other properties if required === Check other available properties in the [[Package_configuration | configuration guide]] === Create simple notification rule === In this example, we will define a rule to notify submitted that defect is closed. We are using standard Defect record from "Defect Tracking" schema. [[Image:submit_Email_Notification_Rule.jpg]] Create new email_notification_rule record [[Image:en_1.jpg]] Set name to some unique value, "Notify Submitter", and record type field to "Defect" (the package must be applied for this record type). Action "Close" will trigger notification, because we specified it in the "Actions" field. [[Image:en_2.jpg]] The email is going to be sent to submitter, and we use "$Submitter.email" variable (extracting email from Submitter ClearQuest reference field). We can also add some statics email addresses here as free text, one email address per line, not other delimiters, i.e. $owner.email my_favorite_email_address@my.domain.com [[Image:en_3.jpg]] We are using free text with embedded ClearQuest record fields to format email body. === Test created notification rule === Close a defect, and check if email was created and sent properly. You can use existing or create new query for en_email_message record type to check email queue, [[Category:Rational]] [[Category:Email_Notification_Package]] 3f037c4f85adbe495b836e69f26aaeeecc9e16f6 0 42 233 114 2013-02-01T14:40:22Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === Parser Bug === Parser bug was introduced in [[Email_Notification_1.4_Release_Notes | Email Notification 1.4 Release]] impacting ability to use user defined functions email notification fields. == Enhancements == === New Predefined variables and functions === UserLoginName predefined variable and two new predefined functions were added {| border="1" width="80%" align="left" cellpadding="5" |- | GetFieldOriginalValue | get field original value |- | GetGroupEmailAddresses | get list of email addresses for active ClearQuest group members |} <br /><br /> == Prerequisites == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be '''used''' with pre-7.0 clients as well. == Read More == * [[Email_Notification_1.4_Release_Notes | Email Notification Package Release 1.4 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 8b340fc75944e4e3bd4cb1144d7e252c08da0705 0 8 235 174 2013-02-01T14:40:59Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package Installation'''</big> == Backup your schema repository and users databases == There is no simple way to uninstall package when schema changes are applied to the user database. Please make sure that you '''created backup''' to be able to roll back the change if necessary. It is strongly recommended to test it on a test copy of your schema first. Also, it would make sense to use it with the same database vendor as your production database. In this case, you can minimize risks and safely deploy the package to your production schema and database later. Are you scared yet? == Download and unpack the distribution == [[Image:extract.jpg]] == Run 'install.bat' from distribution to install and register packages == [[Image:install.jpg]] == Start ClearQuest Designer Package Wizard == [[Image:image002.jpg]] == Select EmailNotification 1.6 package from the list of installed packages == click on 'More Packages' button if not in the list [[Image:image004.jpg | none ]] == Select Schema name to apply the package == [[Image:image006.jpg]] and select package version you would like to apply. == Select record types in your schema, which will be enabled for notification == [[Image:image008.jpg]] == Check schema in and upgrade user databases == [[Image:upgrade_udb.jpg]] == Configuring Package == Proceed to [[EmailNotification_Creating_First_Notification_Rule | Creating First Notification Rule]] section. [[Category:Rational]] [[Category:Email_Notification_Package]] 7422366a190d6b68bf2ba368e93053fc9251b1ef 0 70 236 197 2013-02-01T14:41:26Z Paul 1 wikitext text/x-wiki <big>'''Configuring User Administration Tool for IBM-Rational ClearQuest'''</big> The User Administration tool is extremely flexible. It allows changing the tool behavior or adding customizations, such as setting field default values or adding enhanced field or action validation, without schema modification. Its configuration is stored in the ClearQuest database using udb_property records. These records are protected using Security Context feature and not visible to regular users. In addition, the most critical data is encrypted. You can find currently set property values in the public workspace query "Public Queries\Database_Settings\Properties". {| class="wikitable" cellpadding="10" ! align="left"| Property Name ! Default Value ! Secure ! Comments |- | CONFIG_ADMIN_CREDS | |align="center"| Yes | It is a "secure" property that carries administrative user credentials in username/password format. This user account is used to communicate to the master user repository to query or sync users and groups. |- |CONFIG_AUTO_DB_UPGRADE |align="center"|false |align="center"|No |By default, the User Admin tool operates in the same way as the standard user administration utility: you create and/or modify users and group, and then you have to execute "Upgrade_User_DBs" action to push changes into user databases. Setting this property to non-zero value would force database upgrade every time you save User or Group. Depending on size of your environment (number of users and user databases, database server, etc), there might be some performance drawbacks. If it does not work well for you, you can always switch back to the default procedure by setting this property to zero (or deleting it + logout/login). |- |CONFIG_LOAD_EVERYONE_GROUP |align="center"|false |align="center"|No |A built-in "Everyone" group was introduced with ClearQuest Feature Level 7. This group cannot be modified, and by default, it is not loaded to the User Administration tool. This behavior can be changed by setting this property to non-zero value. There is no reason to lad built-in "Everyone" group, but if you are using pre-FL7 database that has group with this name, it might be a solution. |- |CONFIG_MULTISITE_ENABLED |align="center"|false |align="center"|No |Enables Multisite resource-consuming validations, such as mastership of the groups that you would like to add user to. It might impact performance. Do not set it, unless you are using the tool in multisited environment and you are planning to use the tool from many sites simultaniously. |- |CONFIG_OBEY_MS_ON_CREATE |align="center"|false |align="center"|No |By default, during initial load and synchronizations, all users are loaded into the database regardless of mastership. This behavior can be changed by setting the property to non-zero value. In this case, the load will be limited to locally mastered users and groups, but it will require you to perform load from each site. |- |CONFIG_SUPER_USER_GROUP CONFIG_USER_ADMIN_GROUP CONFIG_PASSWORD_RESET_GROUP | |align="center"|No |By default, ClearQuest user with Super User or User Admin privilege is allowed to create and update users and groups, and Super User only is allowed to delete user or group records (when no associated account exists in the master repository). It can be changed by setting the corresponding property to ClearQuest group name. Members of the group would carry the privilege withing the tool, but they would not be able to use the standard ClearQuest user administration utility (to avoid possible problems and necessity of synchronization). Members of the group set in the CONFIG_PASSWORD_RESET_GROUP are allowed to reset user's password only (execute "Password_Reset" action). |- |CONFIG_GROUP_ADMIN_SUFFIX | |align="center"|No |You can use this property to permit some users to administer specific groups only (add or remove existing users and groups). For instance, by setting this property to "_ADM", you would allow members of Some_Group_Name_ADM to administer Some_Group_Name ClearQuest group without granting them any other permissions. |- |CONFIG_GENERATE_PASSWORD |align="center"|false |align="center"|No |When this property is set to non-zero value, and you create user account with ClearQuest authentication leaving password blank, the system will generate random password and include it in the user notification (it is kept in the "NEW_USER_PASSWORD" property). |- |CONFIG_GENERATE_PASSWORD_CHARACTERS |align="center"|0-9a-zA-Z |align="center"|No |Characters used by password generator |- |CONFIG_GENERATE_PASSWORD_LENGTH |align="center"|8 |align="center"|No |Length of the generated password |- |CONFIG_USER_PROFILE_FIELDS |align="center"|UserPrivileges Groups DB_Subscription_Type DB_Subscription |align="center"|No |User account can be updated using other account as a profile. For example, you can create a user that would mirror access somebody else user account permissions. By default, the other user account User Privileges, Groups, Database subscription type and subscribed databases are copied, but it can be changed by setting CONFIG_USER_PROFILE_FIELDS property with desired set of fields in one-field-per-line format. |- |DEFAULT_USERPRIVILEGES DEFAULT_AUTHTYPE DEFAULT_DB_SUBSCRIPTION_TYPE DEFAULT_DB_SUBSCRIPTION DEFAULT_GROUPS_REQUESTED DEFAULT_PROFILE_CHOICE DEFAULT_PROFILE_OPERATION | |align="center"|No |These properties allow to configure user and group default field values. When you start creating new user, it can be initialized with LDAP authentication type, specific set of user privileges, and be subscribed to specific set of user databases. |- |CONFIG_ENABLE_CUSTOM_FIELD_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom field validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_FIELD_NAME VALIDATE_FIELD_LOGIN_NAME VALIDATE_FIELD_FULLNAME VALIDATE_FIELD_PHONE VALIDATE_FIELD_EMAIL VALIDATE_FIELD_USERPRIVILEGES VALIDATE_FIELD_PASSWORD VALIDATE_FIELD_DB_SUBSCRIPTION_TYPE VALIDATE_FIELD_DB_SUBSCRIPTION VALIDATE_FIELD_GROUPS_REQUESTED VALIDATE_FIELD_USERS VALIDATE_FIELD_GROUPS | |align="center"|No |These properties can contain custom validation hook code for User and Group record fields. There is no need to define all of them when custom validation is enabled. You can define required scripts only. The script is the same as a validation Perl hook: it can use $session and $entity global variables and entire CQPerl API. In case of validation error, '''$result''' variable needs to be set with validation error message. You can take VALIDATE_FIELD_EMAIL property as an example. It checks that user's email address was provided in correct format: <source lang="perl"> my $email = $entity->GetFieldValue($fieldname)->GetValue(); if( $email !~ /^[\w\-\.]+\@[\w\-\.]+$/){ $result = "Email address needs to be specified in email\@mycompany.com format!"; } </source> Please note that DB subscription and type properties are the same for both Group and User record types. You can check record type within the custom hook using <source lang="perl">$entity->GetEntityDefName()</source> API call. |- |CONFIG_ENABLE_CUSTOM_ACTION_VALIDATION |align="center"|false |align="center"|No |This property enables check for custom action validation scripts (described later). Setting it to non-zero value enables validation scripts. When property does not exist or set to zero, custom validation scripts are disabled. |- |VALIDATE_ACTION_<ACTION_NAME> | |align="center"|No |These properties contains custom validation code. Custom validation can be written in Perl, using CQPerl API and $session and $entity global variables. Error message should be assigned to the '''$result''' variable. |- |MAX_LENGTH_FULLNAME MAX_LENGTH_PHONE MAX_LENGTH_EMAIL |align="center"| 50 |align="center"| No | Currently, ClearQuest user full name, phone and email fields are limited to 50 characters. If the limit is changed in the future releases, this property can be set to indicate the new limit. |- |} [[Category:Rational]] [[Category:User_Admin_Tool]] 6c9f338f07eb76f56c42fa8ce414e07eb941d15f 0 13 237 112 2013-02-01T14:41:48Z Paul 1 wikitext text/x-wiki = Email Notification Package and ClearQuest 7.1 = <big>'''The package was tested successfully with ClearQuest version 7.1'''</big> == Code Page Enforcement == <big><font color = "red">'''The following steps were necessary for pre-1.4 release only and no longer required!'''</font></big> <small><small>ClearQuest version 7.1 enforces Code Page settings for packages. If package already applied to your schema, you will see the following "Problem Occurred" message in the new Designer: Show registered packages failed... Failed condition: m_cp != sUnsetCodePage The error message does not tell you names of the failed packages. Please follow the steps below to fix the problem * Add the following line to the '''[General]''' section of "package.ini" files in EmailNotification\1.3 package and UDBProperties\1.1 directories, located in ClearQuest\packages CodePage=1;20127 * After .ini files are updated, re-register packages : (assume ClearQuest 7.1 default location in the example, please update paths when required) packageutil registerpackage EmailNotification 1.3 -unregister packageutil registerpackage EmailNotification 1.2 -unregister packageutil registerpackage EmailNotification 1.1 -unregister packageutil registerpackage EmailNotification 1.0 -unregister packageutil registerpackage UDBProperties 1.1 -unregister packageutil registerpackage UDBProperties 1.0 -unregister packageutil registerpackage UDBProperties 1.1 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\UDBProperties\1.1" packageutil registerpackage EmailNotification 1.3 \ "C:\Program Files\IBM\RationalSDLC\ClearQuest\packages\EmailNotification\1.3" The error message will disappear. If you install package in the new schema repository, it will appear in the package list after completing steps above. You need to restart designer, BTW. (Even if you cannot see the package in the list, you can still use packageutil in command line to apply packages) It is not a critical issue, because you need to install packages and perform these steps on machines where you develop your ClearQuest schema only. There is no need to install package on the clients.</small></small> == Fixed problems == I am glad to announce that the problem with Perl socket library that caused some problems in Eclipse client in 7.0.1 is fixed. The package was successfully tested with all clients, using access and MS SQL Server backend databases and all feature levels. BTW, I would not recommend to deploy 7.1 until first service pack is released, but it is my personal opinion. [[Category:Rational]] [[Category:Email_Notification_Package]] da4fbd5e111cff6bd86744e69d10f967f2c51d7d 0 33 238 57 2013-02-01T14:42:12Z Paul 1 wikitext text/x-wiki <big>'''Delivery Mode'''</big> The package was designed to use Simple Mail Transfer Protocol (SMTP) to deliver generated notification messages. SMTP allows to unify configuration for all ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be the first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you. It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in as well. There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by '''EN_DeliveryMode''' database property. == Deferred Delivery (default) == When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package performs delivery in the following way. [[File:Deferred_Delivery_1.png | center]] When user is executing some action in ClearQuest, email rules are evaluated. All notifications created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server. It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine. [[File:Deferred_Delivery_2.png | center ]] In this case, these messages would be queried when other action is performed later by the same or other ClearQuest client, at the end of rules evaluation cycle (4) and delivered (5). Maximum number of delivery attempts is 5, and can be changed by setting '''EN_DeliveryAttempt''' property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing '''Send Message''' action on the en_email_message records, or by resetting number of delivery attempts on them. == Light Delivery == When notification audit trail is not so important, and you would like to minimize interactions with the database without sacrificing reliability, you can consider using '''Light''' delivery mode. [[File:Light_Delivery.png | center]] In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the messages will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later. == Queue Delivery == Another common way to process notifications is '''Queue''' delivery mode. [[File:Queue_Delivery.png | center]] In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by [http://cqadmin.org/wiki/Download delivery script] (2) running on the ClearQuest server(s). The only requirement for the server is to have ClearQuest installed and database connection configured. ClearQuest Web (CM) servers could be good candidates for scheduled execution of the script, and it might make sense to configure more than one for redundancy. Queue delivery might be extremely useful when sending emails from users' desktops is restricted by security policy, blocked by firewall, or fails due to application bugs (for example, socket library in some versions ClearQuest 7.0 Eclipse client). It also improves end-user performance, in comparison with Deferred mode, as actions are not delayed for sending emails. == Other Considerations == Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely delivery of email even with no user activity on the database. Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to purge the table periodically. A simple script can be found on [http://cqadmin.org/wiki/Download Downloads] page. == Custom Delivery Mechanisms == SMTP along with offered delivery modes should satisfy most of the users' requirements, but sometimes, it might be required to employ custom delivery mechanisms. Fortunately, Queue delivery mode opens this possibility. When Queue mode is used, Email Notification package would ensure that all generated messages are stored in the database, and you can implement desirable delivery protocol by taking simple delivery script as an example and enhancing it. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 858824159e183006d71afa3d8e903b679fea8fc8 0 41 239 129 2013-02-01T14:42:30Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Subscription'''</big> You can allow users to manage their email notification rules subscription preferences. This functionality is delivered with optional EmailSubscription package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. For example, you have constant request from users to be notified about new defects. In order to avoid excessive administrative task, you can open Email Notification rule for self-subscription. === Email Notification Rule === In our example, Email notification rule record would trigger a notification when new defect is created, by "Submit" action. We can either leave recipients list empty, or specify emails where the notification would be sent regardless of subscription. === Create Email Subscription Record === When Email Notification Rule exists, it can be opened for end-users self-subscription by creating Email Subscription record. You can give the record descriptive name, for example, "New Defects Subscription" and specify email notification rule. When record is committed, '''ES_GetSubscribersEmails()''' function will be added in the '''To:''' field of Email Notification Rule. You can update Email Notification Rule to move ES_GetSubscribersEmails() to CC or BCC fields if necessary. End users can manage their subscription by using '''Subscribe_Me''' or '''Unsubscribe_Me''' actions on the correspondent Email_Subscription record. More than one Notification Rule can be associated with Email Subscription record. In multisited environment, Email Subscription record needs to be created for each site where subscription is enabled: end users would be able to update subscription records that are mastered on their local site only. [[ClearQuest_Email_Notification_Package | Back to the package page]] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 0b6aced33e5dff880ca5c80ca34228f49f464137 0 43 240 139 2013-02-01T14:43:41Z Paul 1 wikitext text/x-wiki <big>'''Support of National Charsets'''</big> == International Characters in Email Messages == Most of the modern email clients support national character in the email body. Encoding can be specified in the message envelope using '''Content-Type''' header. For instance, the following line added to the message header would inform email client that email body should be treated as HTML using UTF-8 character set. Content-Type: text/html; charset=utf-8 Nevertheless, what do we suppose to do with international characters in the message envelope, such as email subject or "From" email address? Depending on your environment, there are few options. === Transfer unicode characters in UTF-8 === While it was not originally supported in SMTP protocol, using UTF-8 encoding in message envelopes became standard de facto, and eventually was documented in RFCs extending SMTP protocol. In most of the environments, and for most of the modern email clients it is safe to assume that UTF-8 content can be transferred as-is, and it is default behavior for the Email Notification package. Nevertheless, you still need to specify character set using '''Content-Type''' header as described above. === Transcoding unicode characters === In some rare cases when email client or email server cannot handle UTF-8 encoded characters in the message envelope, a workaround documented in the [http://tools.ietf.org/html/rfc2047|RFC 2047] can be used. The following is an example of user-defined function that can be used to encode UTF-8 strings using Base64 encoding and presenting it in the format specified in the RFC. <br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_Encode_Envelope<br /> | valign="top" | <source lang="perl">my $string = shift; require utf8; require MIME::Base64; utf8::encode($string); $string = MIME::Base64::encode($string); return "=?UTF-8?B?$string?="; </source> |} <br /> When udb_property record is submitted, this user-defined function can be used to safely encode envelope fields that can contain unicode characters, for instance message subject: RT_Encode_Envelope("Defect $ID - $headline") <br /> [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 4cec28b32aa574dd36c8920a77c23733f789347e 0 44 241 143 2013-02-01T14:44:05Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. <br /> == Other Notes == === Supplementary scripts === Supplementary script, such as Delivery Script for Queue delivery mode and Timed Notification script for reminders, need to be updated in order to support non-ascii databases. New versions are available for download from [http://store.cqadmin.com/index.php/clearquest.html CQAdmin store]. == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] d7084c3c75f47670c0368ae74fc0802e859e68d6 0 12 242 137 2013-02-01T14:44:29Z Paul 1 wikitext text/x-wiki <center><big>'''<big>Examples</big>'''</big><br /></center> == '''Defect state updates''' == Send notification to submitter ('Submitter' CQ field - reference to users) when Defect is postponed (with action postpone), rejected (with action reject) or closed (action close).<br /> Do not send notification if submitter is the same user that perform action to avoid email flooding.<br /> We have to test notification rule in test database and migrate it to production without changes (database name in http link should be updated automatically).<br /><br /> We will define two supplementary functions in database properties: <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetUserLoginName<br /> | valign="top" | <source lang="perl"> return $session->GetUserLoginName();</source> |- | width="20%" valign="top" | GetCurrentDatabaseName<br /> | valign="top" | <source lang="perl"> my $dbname = $session->GetSessionDatabase()->GetDatabaseName(); return $dbname;</source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | State change submitter notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Postpone<br /> Reject<br /> Close<br /> |- | width="20%" valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''GetUserLoginName()''' ne '''$Submitter'''<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Your Defect ''''$ID'''' has been '''${state}'''.<br /> Defect title: ''''$Headline''''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> Subject will be evaluated when email notification is triggered, for example:<br /> "Your Defect 'SAMPL00000001' has been Rejected."<br /> We use ${State} notation for state field to avoid ambiguity, because it is followed by '.' (valid symbol for variable name).<br /> Starting version 1.5, '''$UserLoginName''' predefined package variable can be used instead of GetUserLoginName user-defined function<br /><br /><br /> == '''Using SQL query''' == Send notification to clearquest user group 'CCB_Approvers' and submitter when request been resolved<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Resolution Notification (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Actions<br /> (actions)<br /> | valign="top" | Resolve<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> SQL("SELECT T2.email <br /> FROM parent_child_links T1, groups T3, users T2 <br /> WHERE T1.parent_dbid = T2.dbid <br /> AND T1.child_dbid = T3.dbid <br /> AND T3.name = 'CCB_Approvers' <br /> AND T2.is_active = 1")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. Resolution ''''$Resolution''''<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been resolved. <br /> Defect title: ''''$Headline''''<br /> Resolution: ''''$Resolution''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /> You can also create reusable function and put it into properties <br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetGroupEmailAddresses<br /> | valign="top" | <source lang="perl"> my ($groupname) = @_; my $return_string; # SQL statement my $result_set = $session->BuildSQLQuery( "SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = '$groupname' AND T2.is_active = 1"); $result_set->Execute(); # fetch email addresses while( $result_set->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ my $tmp_str = $result_set->GetColumnValue(1); $return_string .= "$tmp_str\n"; } # clear 'errors' $result_set = undef; $@ = ''; return $return_string;</source> |} <br /> In this case 'To' field in Notification rule could be changed to:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email<br /> GetGroupEmailAddresses( 'CCB_Approvers' )<br />''' |} <br /><br /> == '''SQL query and dynamically assigned message priority''' == To simplify defect management, we use assignment or functional group idea.<br /> Defect submitters do not know who is responsible for particular feature, but can guess, what functional area is.<br /> Submitter needs to select Assignment group only.<br /> We need to notify Assignment group manager(s) about new defect assigned to group.<br /> If defect Severity is '1-Critical' or Priority is '1-Resolve Immediately', email message has to be flagged as 'High Priority'.<br /><br /> Possible AssignmentGroups stateless record type implementation: <br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="2" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as '0', valid groups as '1' |} <br /> ''Defect'' record type has Assigned_To_Group field (reference to ''AssignmentGroups''). <br /><br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Notify Group Managers (any unique name)<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Assigned_To_Group<br /> |- | valign="top" | Priority<br /> (Msg_Priority)<br /> | valign="top" | '''$Priority''' =~ /^1/ <nowiki>||</nowiki> '''$Severity''' =~ /^1/ |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''SQL("SELECT T3.email<br /> FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4<br /> WHERE T1.parent_dbid = T4.dbid<br /> AND T1.child_dbid = T3.dbid<br /> AND T1.parent_fielddef_id = T2.id<br /> AND T2.name = 'Managers'<br /> AND T4.name = '${Assigned_To_Group}' ")<br />''' |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' with severity: ''''$Severity'''' and priority: ''''$Priority'''' has been assigned to your team. Please assign it to somebody in your team.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Defect ''''$ID'''' has been assigned to your team. <br /> Please assign Defect to somebody in your team or re-assign it to another team if initial assignment was incorrect.<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Using original field value''' == Starting version 1.4, original value can be accessed using '''GetFieldOriginalValue''' package-defined function, but this example can be used in earlier versions of the package. Notify assignee that defect priority assigned to him has been raised. Valid priorities are '1- something', '2 - something', etc. That simplifies comparison.<br /> Lets create user-defined function that retrieves previous value for field.<br /> udb_property record<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | GetFieldOriginalValue<br /> | valign="top" | <source lang="perl"> my $name = shift; my $value = '' ; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value;</source> |} <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Priority has been raised - notify assignee<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Field Change<br /> (Field_Change)<br /> | valign="top" | Priority<br /> |- | valign="top" | Condition<br /> (Msg_Condition)<br /> | valign="top" | '''$Priority''' gt '''GetFieldOriginalValue('Priority')''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | Priority has been raised for defect ''''$ID'''' from ''''GetFieldOriginalValue('Priority')' '''to ''''$Priority''''<br /><br /> Defect title: ''''$Headline''''<br /> Severity: ''''$Severity''''<br /> Priority: ''''$Priority''''<br /> Description: <br />'''$Description'''<br /><br /> <nowiki>http://newcqweb-server/cqweb/main?USE_CASE=GO&service=CQ&schema=DBSET&contextid=</nowiki>'''GetCurrentDatabaseName()'''&entityID='''${dbid}'''&entityDefName=Defect<br /><br /> |} <br /><br /> == '''Sending HTML Emails''' == We need to specify proper '''content type''' in the message header ("Header add-in" field). When it is done, we can use HTML in the message body, highlighting text, using different fonts and colors, etc. <br /> Notification rule:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | My first HTML email<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | valign="top" | Header add-in<br /> (Msg_Header)<br /> | valign="top" | '''Content-Type: text/html; charset=us-ascii''' |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$owner.email<br />''' |- | valign="top" | Subject<br /> (Msg_Subject) | valign="top" | HTML test message for defect ''''$ID'''' |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="xml"> <HTML> <BODY> <H2 ALIGN="left">$EntityDefName $ID</H2> <TABLE ALIGN="left" BORDER="1"> <TR><TD><b>ID</b> </TD> <TD>$id </TD></TR> <TR><TD><b>headline</b></TD> <TD>$Headline</TD></TR> <TR><TD><b>Priority</b></TD> <TD>$Priority</TD></TR> <TR><TD><b>Severity</b></TD> <TD>$Severity</TD></TR> <TR><TD><b>Description</b></TD> <TD><PRE>$Description</PRE> </TD></TR> </TABLE> </BODY> </HTML> </source> |} <br /><br /> == '''Sending Emails with Attachments''' == Fist of all, it is not recommended to attach large files to email messages. It might significantly impact your application performance. It would work better if you could send an URL to the record, or the file, but sometimes, attaching files to emails is the only solution. In this case, we will define two supplementary functions: one to check for attachments, and another to add attachments to email. <br /> udb_property records:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RT_HasAttachments<br /> | valign="top" | <source lang="perl"> # checks for attachment on current entity # returns true or false respectively my ($result, $i); my $att_fields = $entity->GetAttachmentFields(); # check for attachments in all Attachment type fields for($i = 0; $i < $att_fields->Count(); $i++ ){ my $att_field = $att_fields->Item($i); if($att_field->GetAttachments()->Count() > 0 ){ $result = 1; # attachment exists last; } } # TRUE if current record has attachment return $result; </source> |- | width="20%" valign="top" | RT_InsertAttachments<br /> | valign="top" | <source lang="perl"> # add attachments to email require MIME::Base64; my ($result, $tmp, $attachments, $attachment, $file, $tmpfile, $nload, $i, $k, $num); # get all fields of attachment type my $att_fields = $entity->GetAttachmentFields(); my $dbid = $entity->GetFieldValue('dbid')->GetValue(); # create unique boundary separator my $boundary = "Boundary_($dbid)"; # get temporary directory location where to extract attachments $tmp .= '/' if (($tmp = $ENV{TMP}) ne '' || ($tmp = $ENV{TEMP}) ne ''); $tmp = '/tmp/' if ( $tmp eq '' && $^O ne 'MSWin32' ); for($i = 0; $i < $att_fields->Count(); $i++ ){ # for all attachment fields: my $att_field = $att_fields->Item($i); if( ($num = ($attachments = $att_field->GetAttachments())->Count()) > 0 ){ for($k=0; $k < $num; $k++){ # for all attachments in the field # get attachment $attachment = $attachments->Item($k); # get the file name $file = $attachment->GetFileName(); if( $file =~ /[\\\/]/ ){ # if the file has path delimiters – it has not been loaded yet # (file attached in current action?) # we can use its original location $tmpfile = $file; # remove path delimiters # and set ‘do not load’ flag $file =~ s/.*[\\\/]//; $nload = 1; }else{ # otherwise - create a temporary file name $tmpfile = "$tmp$dbid.$k.txt"; # unset ‘do not load’ flag $nload = 0; } # load attachment from record into temporary file if( $nload || $attachment->Load($tmpfile) ){ # open the attachment file open(TMPFILE, $tmpfile) or die "Cannot open file '$tmpfile'\n"; # set file handle to binary mode binmode TMPFILE; # unset record delimiter local $/ = undef; # encode content of the file with Base64 encoding my $content = MIME::Base64::encode_base64(<TMPFILE>); # close the file close(TMPFILE); # and delete it, if it was a temporary file # created to save the attachment unlink($tmpfile) unless $nload; # add header and encoded attachment to the message $result .= " --$boundary Content-type: application/octet-stream Content-transfer-encoding: base64 Content-disposition: attachment; filename=$file $content\n"; } } } } # return encoded attachment return $result; </source> |} <br /> Email_Notification_Rule fields:<br /> {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Name<br /> (name)<br /> | valign="top" | Sample notification with attachments<br /> |- | width="20%" valign="top" | Record Type<br /> (Entity_Def)<br /> | valign="top" | Defect<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "MIME-Version: 1.0 Content-type: multipart/mixed; boundary=\"Boundary_\($dbid)\"")</source> |- | valign="top" | To<br /> (Msg_To_Users)<br /> | valign="top" | '''$Submitter.email'''<br /> |- | valign="top" | Subject<br /> (Msg_Subject)<br /> | valign="top" | Defect ''''$ID'''' has been '''${state}'''.<br /> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text">IF( RT_HasAttachments(), "--Boundary_\($dbid) Content-type: text/plain; charset=us-ascii") Defect $ID Headline: $Headline Description: $Description RT_InsertAttachments() </source><br /><br /> |} <br /><br /> == '''Sending Consolidated Queries or Reports Using Timed Notification''' == Timed notification was created to trigger alerts for individual records, but can it be used to send consolidated reports? There are few ways to achieve it. If you are using CQWeb 7.1 or later, you can employ data-pull reports and send URL to the users. No notification would be ever required in this case. Another way would be to create scheduled notification to run some queries (or reports) and send results to the users. First of all, I would like to create new record type, scheduled_queries, that might look like this {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Field Name ! width="20%" valign="top" | Field Type ! valign="top" | Description |- | width="20%" valign="top" | '''Name''' | valign="top" | SHORT_STRING | valign="top" | unique identifier of the scheduled query |- | width="20%" valign="top" | '''Frequency''' | valign="top" | SHORT_STRING | valign="top" | choice list: daily, weekly, monthly, etc |- | width="20%" valign="top" | '''Active''' | valign="top" | INT | valign="top" | active/inactive 1/0 checkbox to deactivate entry without removing it from the database |- | width="20%" valign="top" | '''Path''' | valign="top" | MULTILINE_STRING | valign="top" | path to the query in the workspace. Multiline type is preferred to avoid 254 symbols limitation |} <br /> After creating the record type, applying Email Notification package to the record, and upgrading user database, you can configure timed notifications for the new record type. The scope can include all active records of the new record type. No condition is required. The following user-defined function can be used to execute query and extract query result in the form of HTML table (we can call it "RETURN_QUERY_RESULTS_AS_HTML_TABLE"): {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Name<br /> ! valign="top" | nm_value<br /> |- | width="20%" valign="top" | RETURN_QUERY_RESULTS_AS_HTML_TABLE<br /> | valign="top" | <source lang="perl"> my $query_path = shift; # change path to UNIX style $query_path =~ s/\\+/\//g; # resulting HTML table my $table = "<TABLE BORDER=\"1\" CELLPADDING=\"10\">\n"; # query fields my @fields = (); # get workspace my $ws = $session->GetWorkSpace(); # get query definition my $qdef = $ws->GetQueryDef($query_path); my $field_defs = $qdef->GetQueryFieldDefs(); my $count = $field_defs->Count(); for( my $i = 1; $i < $count; $i++ ){ my $field_def = $field_defs->Item($i); my $name = $field_def->GetLabel(); my $type = $field_def->GetFieldType(); push(@fields, { name => $name, type => $type }); } # Create Table Header row $table .= '<TR>'; foreach my $field (@fields){ $table .= "<TH><b>$field->{name}</b></TH>"; } $table .= "</TR>\n"; # execute query my $resultset = $session->BuildResultSet($qdef); $resultset->Execute(); # create data rows while( $resultset->MoveNext() == $CQPerlExt::CQ_SUCCESS ){ $table .= '<TR>'; for( my $i = 2; $i <= $count; $i++ ){ my $value = $resultset->GetColumnValue($i); $table .= "<TD>$value</TD>"; } $table .= "</TR>\n"; } $table .= "</TABLE>\n"; #return HTML table $@ = ''; return $table;</source> |} <br /> Then we can use it in the timed notification rule body field, something like: {| width="100%" border="1" cellspacing="2" cellpadding="2" ! width="20%" valign="top" | Form Field Name<br /> (CQ field name)<br /> ! valign="top" | Value<br /> |- | width="20%" valign="top" | Header Add-in<br /> (Msg_Header)<br /> | valign="top" | <source lang="text">Content-type: text/plain; charset=us-ascii</source> |- | valign="top" | Body<br /> (Msg_Body)<br /> | valign="top" | <source lang="text"> <HTML><BODY> something you would like to to say about scheduled query $Name RETURN_QUERY_RESULTS_AS_HTML_TABLE($Path) </BODY></HTML> </source><br /><br /> |} Timed Notification triggers the rule, all query records are selected, query executed and formatted as HTML table, and email is sent to the users. From that moment, it is easy to maintain: you can add new scheduled queries just by submitting new records of the "scheduled queries" record type and specifying new query path, and you can update content of the emails by editing queries in the workspace. <br /> [[Category:Rational]] [[Category:Email_Notification_Package]] ca78ff91618d8d349fdf92a8bc8d25e251eefc19 0 10 243 63 2013-02-01T14:44:47Z Paul 1 wikitext text/x-wiki =Timed Notification= == What does Timed Notification mean? == Sometimes we would like to implement notifications that are not triggered by particular action. You might need a reminder that defect approached a resolution deadline, or that a trouble ticket passed due date, was not implemented in time frame required by the Service Level Agreement, was not assigned for implementation in a reasonable time frame. I call such kind of requests Timed Notifications or Reminders. == How Timed Notifications / Reminders are implemented? == There are two parts of the complicated task # find records that could be eligible for notification # trigger notifications based on information in selected records === How to find records? === To make it flexible and to avoid waste of resources, the selection process is implemented in two phases: # '''Initial records selection''' selects records that might be eligible, define notification scope. #: It would be too expensive to check evaluate every ClearQuest record to determine whether or not notification condition met. In order to improve performance and reduce load on the database, we need to reduce number or records for evaluation. For example, when implementing due date reminder, we could safely exclude closed or resolved defects. It could be different in other cases, but the main goal would always be defining potential notification scope, then # '''Final selection''' evaluates notification rules on selected at step (1) records and triggers notification if condition is met (for example, the record passed due date). ==== Initial records selection ==== It is limiting scope based on simple criteria that can be used in a SQL Query to retrieve records. For example, you can limit records based on record type, current state, severity, assignment, etc. Timed Notification script offers you two possibilities: # create a ClearQuest query, and save it in the public workspace # specify criteria to create the query dynamically during the execution ==== Final selection ==== In addition, records can be filtered based on Email Notification Rule ''Condition'' field. It is performed during evaluation of notification rules on the record set selected on the previous step. Rules evaluation is expensive process that is why it very is important to have good initial record selection. === Triggering notifications === Since we are using extremely customizable email notification rules for other actions, it makes sense to use the same functionality, and keep timed notification rules at the same place. Regular notifications are triggered by ''actions'', timed notifications - by ''pseudo-actions''. It means that in reality no action is executed, but the script evaluates email notification rules on selected records in the same way as it would be done if the real action would be invoked. If you noticed, selection of actions on Email Notification Rule record is not limited to actions defined for the record type, and it is done on purpose: you can specify there non-existent, '''pseudo-action''' name. To make all thins working, you just need to * create a notification rule, using ''pseudo-action'' * run the script using the ''pseudo-action'' as a parameter * let script know the record types that it will be running on and the way to limit record set for notification rules evaluation. ClearQuest does not have any server based process like cron that can trigger actions. It can be changed in the future (the new ClearQuest Web Server includes request manager that does not have any public interface so far), but as of today, the only way to trigger timed email notification is to run timed notification script from UNIX cron or Windows scheduler on your ClearQuest server. You can download timed notification script [[Download | here]]. == Configuration == For example, we would like to notify assignees about defects that will pass due date in the next 24 hours. I will name pseudo action used in this example '''DailyNotification''' The following tasks need to be accomplished === Configure Scheduler on a ClearQuest server === CQ Web server could be a good candidate to run the script. The following script need to be configured to run daily, let's say at 4 AM <source lang="bash"> cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification" </source> === Enable Notification for the record type === In this example, we need to inform the script that it is running on ''Defect'' record type. In order to do it, '''TN_RecordTypes''' property need to be set to '''Defect''' (udb_property record type has to be submitted with "Defect" value) '''Note''': '''TN_RecordTypes''' property value can contain more then one record type. A list of enabled record types has to be specified as '''one-record-type-per-line'''. === Create email notification rule === Email Notification Rule for Defect record type (major fields) {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Field ! Value |- | Name | Defect_Reminder |- | Record Type | Defect |- | Actions | '''DailyNotification''' |- | Condition | <source lang="perl"> $Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0 </source> |- | To: | <source lang="perl"> ${owner.email} </source> |- | Subject: | <source lang="text">Defect $ID will pass due date $Due_Date soon</source> |- | Body: | <source lang="text">You need to do something with defect $ID</source> |} === Limit record set for notification rules evaluation === It would be too expensive to evaluate the notification rule on each record. It is a good idea to limit an evaluation scope. As it was discussed above, there are 2 ways to do it. ==== Create query in ClearQuest client ==== For example, we can create query that will filter open defect, save as "Public Queries\Admin\DailyNotificationQuery" and set '''TN_Query-Defect-DailyNotification''' property to that value. When script is executed, it checks '''TN_Query-{record type}-{pseudo action name}''' or '''TN_Query-{record type}''' properties if the first one is not defined. '''Note:''' You could have both '''TN_Query-{record type}''' and '''TN_Query-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_Query-{record type}-{pseudo action name}''' would overwrite default value if specified. ==== OR provide filter criteria for dynamic query ==== This way you can specify state names that have to be excluded from the notification. Based on information provided, script will create a query at run time. The states can be specified using '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' or '''TN_QueryExcludeStates-{record type}''' property in one-state-per-line style. In our case, we can submit '''TN_QueryExcludeStates-Defect-DailyNotification''' property with the following values: Submit Closed If 'TN_Query-{record type}-{pseudo action name}' and 'TN_Query-{record type}' properties do not exist, the script checks for excluded state properties and uses them as a filter in run-time created query. '''Note:''' You could have both '''TN_QueryExcludeStates-{record type}''' and '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' properties in your database. The first one would work as a default value for all action names, while '''TN_QueryExcludeStates-{record type}-{pseudo action name}''' would overwrite default value if specified. == Properties used in Timed Notification script == {| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top" ! Property name ! Description |- | valign="top" | '''''TN_RecordTypes''''' | list of record types enabled for the timed notification script<br /> |- | valign="top" | '''''TN_Query-{record type}-{action name}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for pseudo action {action name} (from the script command line)<br /> Overwrites TN_Query-{record type} property when exists. |- | valign="top" | '''''TN_Query-{record type}''''' | Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for any pseudo action name |- | valign="top" | '''''TN_QueryExcludeStates-{record type}-{action name}''''' | a set of record states, one per line, that will be filtered out in run-time query for pseudo action {action name}, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist.<br /> Overwrites TN_QueryExcludeStates-{record type} property when exists.<br /> |- | valign="top" | '''''TN_QueryExcludeStates-{record type}''''' | a set of record states, one per line, that will be filtered out in run-time query for any pseudo action, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist. |} <br /> <br /> [[Category:Rational]] [[Category:Email_Notification_Package]] 1f48fcf0644df98816a61fec428933b14a9bb6f4 0 69 244 198 2013-02-01T14:45:05Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool Installation'''</big> == Planing the Installation == User Administration Tool for IBM-Rational ClearQuest is a ClearQuest database. The installer will add a custom schema to your schema repository, create user database associated with the schema, and load all data. Before you proceed, you need to collect: * Physical Database information of empty database (DB vendor, server, database name, database user account, and connect options). The database needs to be created in advance (unless you are going to use Microsoft Access). * Email notification settings - SMTP server name and email user credentials (if password authentication is required with SMTP relay). You can check [[Package_configuration | Email Notification Package Configuration]] page for additional information. * Obtain local administrative rights on the machine where you are going to perform the installation. * Create (or use an existing) ClearQuest account with Super User right that will be used for user account management. It is recommended to use ClearQuest authentication for the account to avoid problems related to password expiration. == Backup Schema Repository Database == It is always a good idea to create a backup before you making any change to the schema repository to roll back the change if necessary, and I strongly recommend to install the tool in your testing environment first: you would be able to validate that it is compatible with your environment and database vendor. It would minimize risks associated with deployment of the tool in your production environment later. == Installing User Admin Tool == You can install the tool using any machine that has IBM-Rational ClearQuest installed and ClearQuest connection configured. First, unpack User Administration Tool distribution to local or network drive (you cannot start installation from network location referenced via UNC path), and launch '''install.bat''' located in the root of the distribution. [[File:user_admin_install.png|none]] <br />On Windows 7 and Windows 2008 machines you need to select "Run as Administrator" option explicitly, and allow making changes [[File:user_admin_install_2.png|none]] <br />Login to the ClearQuest using connection (dbset) that you would like to enable for user administration using Super User account you created on the "planning..." step. [[File:user_admin_install_login.png|none]] <br />Provide required information to create ClearQuest User Administration database. Depending on your database vendor and environment, you might need to provide additional connection options. Please check ClearQuest administration manual for details. If you aborted the installation for any reason after user database was created, you would be allowed to select user database created earlier instead of creating a new one. [[File:user_admin_db_settings.png|none]] <br />Verify that you entered all information and click on "Create DB" button. The installer will start creating user database and importing all user data. There is no progress indicator, please be patient. Depending on database server load and number of user accounts the initial load might take significant time. For example, in my local environment it takes about 15 minutes to load 3000 users and groups. When user database is created and data import is completed, the installer will offer you to configure email notification setting. Please provide required information and save settings. The installer will validate SMTP server connectivity. [[File:user_admin_en_config.png|none]] <br />It is the last step in the installation procedure, and no error occurred, you should receive the following confirmation. [[File:user_admin_install_completed.png|none]] <br />Congratulations! You have completed your installation. Log in to the ClearQuest database you created and you can start using it immediately. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:User_Admin_Tool]] efda0c0d67349743d2f37880f54e534242191515 0 32 246 123 2013-02-01T14:45:52Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <p>Frequently asked questions == Installation == === What version of ClearQuest the package Can be used with? === EmailNotification 1.5 can be installed using ClearQuest Designer 7.0 or later. No additional modifications are required. For older versions of the package, ClearQuest 2001A and later versions are supported. In order to use EmailNotification 1.3 with ClearQuest 7.1, CodePage entry needs to be added in the '''[General]''' section of "package.ini" files. Detailed instructions are provided on the following page: [[ClearQuest_7.1]] === Do I need to deploy the package on each ClearQuest client? === There is no need to install the package on CQ clients. ClearQuest package is applied to a schema and needs to be deployed on machines where you perform development of new schema versions only. === Can I use the package with VBScript-based schema? === Yes, the package can be used with VBScript or Perl schema. Package extensions can be implemented with Perl. === Can I apply package to a stateless record type? === It is possible. This option is now available in wizard, but you can use command line as well. Please check [[Applying_Package_to_Stateless_Records | applying package to a stateless records]] page for details. == Configuration == === Can I create HTML emails? === Absolutely! You can set proper content-type in the email header (Header Add-in field), and use HTML the email body. This RFC-compliant email will be properly recognized by most of the email clients. Please check [[Notification_Examples#Sending_HTML_Emails | examples]] page. === Can I send attachments with notifications? === It is not recommended to attach large files to notifications, as it can impact performance of ClearQuest application. Nevertheless, it is possible. You can find detailed instructions on the [[Notification_Examples#Sending_Emails_with_Attachments | examples]] page. === Where can I find notification rule examples? === # [[Notification_Examples | Notification examples]] # [[Package_configuration | Package configuration guide]] # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [http://forum.cqadmin.org/ Support forum] === In multisited environment, can I use different SMTP relays for different sites? === Yes, it is possible by defining site-specific property for email_host, i.e. if your site name is '''Atlanta''', Atlantaemail_host would work as email_host property for that specific site only. You can also unset paticular property by using '''EN_NONE''' as a value. === Can I call one User Defined function from another? === Yes, you can use '''EN_CALL_UDF''' function and supply other function name and parameters, but it is not the only way to reuse functionality. You can also define "common block" in a database property and "include" it in other user defined functions. For example, you can defined property that contains common function definitions {| border="1" width="60%" ! width="40%" | Property Name ! Value |- | MY_COMMON_BLOCK | <source lang="perl">sub func1 { ... } sub func2 { ... } sub func3 { ... } </source> |} and then re-use it in other user-defined functions {| border="1" width="60%" ! width="40%" |Property Name ! Value |- | MY_FUNCTION | <source lang="perl"> eval GetProperty('MY_COMMON_BLOCK'); ... </source> |} === Can I customize the package for my own needs? === You can enable package editing and add customization. # close ClearQuest designer and enable package editing from command line: #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -enable <login_name> </source> #: where "[-dbset <dbset>]" is a specification of schema repository connection name that was configured in ClearQuest Maintenance Tool. It can be omitted if you have only one configured schema repository. # open schema in Designer and update Submit action access controls for udb_property and Email_Notification_Rule record types (for example, limit to a group) # test your changes # disable package editing from command line to prevent accidental modifications #; <source lang="bash"> packageutil enableediting [-dbset <dbset>] <login_name> <password> -disable <login_name> </source> # check the schema in, and promote changes to production database Nevertheless, I would recommend researching first, if is it possible to achieve what you are going to implement using functionality available in the package, as your changes will be overwritten when new package release is installed. == Troubleshooting == What if the package is not doing something that you would expect it to do? * Verify that the package is applied to selected record type. : When package is applied, you should see "EN_NotifyHook" in the Perl Record Script section of the record. * Verify that '''email_enabled''' database property (udb_property record) is created and set to non-zero value * Check if en_email_message record is created. : en_email_message records are always created when Queue or Deferred (default) delivery mode is used. If you are using Light delivery mode, switch to Deferred until troubleshooting is completed. * Turn On Debugging : Create '''Debug''' database property (udb_property record), set it to desirable log level (up to 9), and capture debug output using '''dbwin32.exe''' utility. * You can always ask for help on [http://forum.cqadmin.org/ support forum]. == Known Issues == [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] b10490671ce4f3232ac4538fd301b65373c36672 0 39 248 108 2013-02-01T14:46:41Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.4'''</big> <big>'''Release Notes'''</big> == Bug Fixed == === SMTP Header Line Length Limit === A workaround was implemented preventing address lines with multiple recipients exceeding 1000 characters. It could break SMTP header in previous version. === Creating Perl interpreter failed === A fix for an intermittent issue was implemented. Thanks to Adam Skwersky. === A dot after variable name === In a parameterized text field, a dot placed immediately after variable name is no longer causing any issues. === Multiline SQL queries and DB2 === An issue was resolved that was causing issues with some releases of DB2 database. == Enhancements == === ClearQuest 7.1.x installation === ClearQuest 7.1.x installation was improved === Expressions in function list of parameters === In list of parameters, there no need to use brackets around expressions. For example, <source lang="perl">IF( $a > $b, "a", "b" )</source> === $EmailNotificationRuleName built-in variable === New built-in variable, $EmailNotificationRuleName, was introduced to carry evaluated rule name. === Rules Evaluation Order === You can change Notification Rules evaluation order. Sort key is a text field. All rules are sorted in ascending order by the Order field. === FROM Email address === A parameterized text field was added to Notification rule to customize From address. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and email_from database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address === Applying package to a stateless record === Package can be applied to a stateless record type using package wizard (using command line was required in previous release). In order to apply to a record type that belongs to a package, package editing needs to be enabled. === Email self-subscription === Optional self-subscription functionality is available with optional EmailSubscription package. === Access controls === Unified access control was implemented. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> == Prerequisites == === ClearQuest client version === The package can be '''installed''' using ClearQuest 7.0.0 or later. Nevertheless, it can be '''used''' with pre-7.0 clients as well. == Read More == * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] == Downloads == [http://cqadmin.org/wiki/Download Download Package] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 0567c3ec057b092e0d31677a6bd38955f0d8edd3 0 7 249 117 2013-02-01T14:47:02Z Paul 1 wikitext text/x-wiki <big>'''Configuration guide'''</big> __TOC__ *The package is implemented in Perl and can be used with Perl-based as well as VBScript-based schemas. *The package does not require Perl modules deployment on clients; all code elements are stored in ClearQuest schema. *The packages use ClearQuest Security Context feature and require metaschema version 22 (ClearQuest repository that created with CQ 2001a and higher or upgraded to 2001A from previous releases). *The package works with ClearQuest clients 2001A, 2002, 2003, and v7 (as of 12/07/2008, 7.1 has not been tested yet). The following platforms are supported: Windows, old CQWeb (ASP-based version), CQWeb (Java Web), ClearQuest UNIX. = Installation = Please refer to [[Package_installation | installation instructions]] page. You will need to install the latest version of EmailNotification package only. UDBProperties will be installed automatically for you. <br /> EmailSubscription is an optional package delivering end-user self-subscription functionality. '''Note:''' Staring 1.4 release, the package can be installed on ClearQuest 7.0 Designer machine, but still can be used with older clients, if necessary. = Configuration = == Email Notification properties == Email notification package properties are ClearQuest records of udb_property record type. Configure property usually means submitting record of that record type. The following properties can be configured for Email Notifications package: ===email_host=== It is your SMTP mail relay. If you need to specify non-default port, it can be done in ''host:port'' combination. Examples: ''mail.provider.net'', ''mail.provider.net:625''. ===email_login (optional)=== login name that is used for password authentication with SMTP relay. If you SMTP relay does not require password authentication, you do not need to use this property, and it shoul not exist. '''Note:''' If you would like, it can be a 'Secure' property. ===email_password (optional)=== password that is used for password authentication. If you SMTP relay does not require password authentication, you do not need this property, and it should not exist. '''Note:''' It is a good idea to use 'secure' property feature when storing it in a ClearQuest database. ===email_address (optional)=== Static "From:" email address for notification. Email address of current ClearQuest user is used if property does not exist. '''Note:''' This feature might be useful to bypass mail relaying restrictions: some SMTP relays may restrict mail relaying based on FROM email address. In case of password authentication, it might be also critical: FROM email address could be restricted to email address of the account used for authentication. Ask your SMTP relay admin for additional information. ===email_reply_to (optional)=== Static Reply-To address, if different from email_address can be specified. For example, you can configure mail replies to be sent to some distribution list. ===email_enabled=== It is the second mandatory property (besides email_host). It has to be set to '1' to enable email notification for user database. By setting it to '''0''' (or by deleting property), you can disable email notification on entire ClearQuest database ===EN_DeliveryMode (optional)=== The following delivery modes are available. Please check [[ClearQuest_Email_Notification_Package_Delivery_Mode | Email Notification delivery mode]] page for details. {| style="width: 60%; height: 88px; text-align: left" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 10%" | '''Light''' | style="vertical-align: top; width: 60%" | deliver notifications "on the fly" and log only error messages for re-delivery, |- | style="vertical-align: top; width: 10%" | '''Deferred''' | style="vertical-align: top; width: 60%" | (default) save all messages before attempting delivery, and deliver them in the same notification hook |- | style="vertical-align: top; width: 10%" | '''Queue''' | style="vertical-align: top; width: 60%" | save all messages in the message queue, and do not attempt to deliver them. Delivery will be done by a separate script running by scheduler on the server. You can find simple delivery script on [[Download]] page. |} ===EN_DeliveryTimeout (optional)=== Delivery timeout interval in seconds. If message in the message queue was not delivered it will be re-delivered (by other user, for example) after that. :Default value: 300 (5 minutes) ===EN_DeliveryAttempt (optional)=== Maximum number of delivery attempts performed for a message in the queue. :Default value: 5 ===EN_DeliveryScript (script only)=== Should never be set in a ClearQuest database. To be used in Delivery script only. ===EN_AdminGroup=== Email administrators group. It is used in en_email_message action access control hooks If it is not set, only user with superuser can modify or delete email messages in the queue. ===Debug (optional)=== Debug level 1-9. Setting this property forces script to trace execution. Output could be captured by using dbwin32.exe utility :Default value: NONE ===Notification_Default_Security_Group (optional)=== Default visibility value. Existing udb_visibility record name that is used as a security context default value in Email_Notification_Rule submit action. ===EN_Disable_Variable_Name_Validation (optional)=== By default syntax of all parameterized fields and variable names are validated. You can turn off variable names check by setting this property to non-zero value. ==Notification Rules== To create notification rule, Submit new Email_Notification_Rule record. Here are some important fields of this record type {| style="width: 80%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name''' | style="vertical-align: top" | any unique name |- | style="vertical-align: top; width: 15%" | '''Record_Type''' | style="vertical-align: top" | desirable record type for which notification package is applied |- | style="vertical-align: top; width: 15%" | '''Order''' | style="vertical-align: top" | Notification Rules evaluation order, SHORT_STRING(10). The rules are sorted in ascending order. |- | style="vertical-align: top; width: 15%" | '''Actions''' | style="vertical-align: top" | notification can be restricted for set of actions. Notification is Triggered for any action if empty |- | style="vertical-align: top; width: 15%" | '''Field Change''' | style="vertical-align: top" | notification can be triggered by filed change. <br /> Triggered regardless any of fields change if empty. <br /> Fields changed in Action or Field initialization hooks are not counted. |- | style="vertical-align: top; width: 15%" | '''Condition''' | style="vertical-align: top" | Notification condition. Notification is triggered if notification condition evaluation result is TRUE. See section expression field syntax for reference. Assumed "TRUE" when the field is empty. |- | style="vertical-align: top" | '''Priority''' | style="vertical-align: top" | Message priority patameterized field, expression can be used. See expression field syntax section for reference. if evaluation result * < 0, message priority is Low. * == 0, message priority is Normal * > 0, message priority is High <br /> Condition result is assumed 0 when the field is empty ('Normal' priority). |- | style="vertical-align: top; width: 15%" | '''From''' | style="vertical-align: top" | "From:" addresses (parameterized). see parameter fields section for syntax reference. # when Notification Rule From field is not empty, it is expanded and used as from address on generated email # when From field is empty, and '''email_from''' database property exists, email_from content is evaluated to be used as from address # otherwise, email address of the user executing action triggering email is used as from email address <br /> One email address is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''To''' | style="vertical-align: top" | "TO:" addresses (parameterized). see parameter fields section for syntax reference. <br /> One email address per line is expected as evaluation result. |- | style="vertical-align: top; width: 15%" | '''CC''' | style="vertical-align: top" | "CC:" addresses (parameterized). One email address per line is expected as evaluation result. |- | style="vertical-align: top" | '''BCC''' | style="vertical-align: top" | "BCC:" addresses (parameterized).<br /> One email address per line is expected as evaluation result.<br /> |- | style="vertical-align: top" | '''Header Add-in''' | style="vertical-align: top" | Additional lines to be included in message header (envelope) - parameterized field. You can use it to specify content type, charset, etc. Please check [[Notification_Examples | notification examples]] page (HTML emails, attachments) |- | style="vertical-align: top; width: 15%" | '''Subject''' | style="vertical-align: top" | Subject - parameterized field. Can be multiline, converted to single line and included into the message header after evaluation. |- | style="vertical-align: top; width: 15%" | '''Body''' | style="vertical-align: top" | message body (parameterized). |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top" | Notification rule can be deactivated by clearing "active" flag. |} '''Notes''' *Notification is triggered only if Action AND Field restrictions are satisfied AND Condition is true AND any of message recipients ("To:", "CC:", or "BCC") fields are not empty after evaluation. *You can create site specific properties in multisited environment as <SiteName>PropertyName. If you would like to disable a global property on specific site, you could do it by setting <SiteName>PropertyName value to "EN_NONE". =Parameterized Text and Condition fields Syntax= ==Parameterized Text fields== Text field can contain plain text, variables that are expanded during rule evaluation, SQL statements, user-defined, pre-defined and Perl build-in functions. Any character in the field can be escaped with '''\'''; ===Variables=== ====Variable Syntax==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''${var_name}''' | style="vertical-align: top" | or |- | style="vertical-align: top; width: 20%" | '''$var_name''' | style="vertical-align: top" | |} Variables are evaluated (expanded) in the following order: * Check if property with the same name defined in CQ database and return value * Check predefined variable names and return value. * Check record field with the same name. <br /> (you can use dot, '''.''', in the name for reference field data type - $name1.name2.name3) <br /> ====Predefined variable names==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''$Action''' | style="vertical-align: top" | current action name |- | style="vertical-align: top; width: 20%" | '''$EntityDefName''' | style="vertical-align: top" | current entity definition. |- | style="vertical-align: top" | '''$SiteName''' | style="vertical-align: top" | Site name in multisited environment |- | style="vertical-align: top" | '''$UserLoginName''' | style="vertical-align: top" | Login name of user triggering email notification rule |- | style="vertical-align: top" | '''$EmailNotificationRuleName''' | style="vertical-align: top" | Email Rule name that is currently evaluated |} ====Examples:==== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | <source lang="perl">$State</source> | style="vertical-align: top" | state field value |- | style="vertical-align: top; width: 20%" | <source lang="perl">$owner.email</source> | style="vertical-align: top" | owner's email (REFERENCE field data type) |- | style="vertical-align: top; width: 20%" | <source lang="perl">${Property_Name}</source> | style="vertical-align: top" | value of database property "Property_Name" (udb_property record) |} '''Notes:''' * Property names and Build-in Environment variables are case sensitive, while Field names are case insensitive! * Date_Time variables: format that is used for Date_Time variable type inside ClearQuest hooks is '''yyyy-mm-dd hh:mm:ss'''. <br /> ===SQL statements=== SQL statement that will be passed to the backend database when variable is expanded. {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" | '''SQL(<statement>)''' | style="vertical-align: top" | SQL execution function<br /> |} *Statement could be Double-Quoted string with variables, functions and SQL statements, single-quoted non-expandable string, or result of function that returns scalar value. *Statement string (SQL function parameter) is not limited to single line. *Statement is executed in run-time using BuildSQLQuery API call and inherited all restrictions related to the API call. Please check ClearQuest API documentation. '''Examples:''' * Get owner's email (the same result as $owner.email) <br /> SQL(" <source lang="sql"> SELECT T1.email FROM users WHERE T1.login_name = '$owner' </source> ")<br /> * Notify 'CHCD_Approvers' ClearQuest group members <br /> SQL(" <source lang="sql"> SELECT T2.email FROM parent_child_links T1, groups T3, users T2 WHERE T1.parent_dbid = T2.dbid AND T1.child_dbid = T3.dbid AND T3.name = 'CHCD_Approvers' AND T2.is_active = 1 </source> ")<br /> * Here is a little bit more complicated scenario: assume that we use AssignmentGroups stateless record type at our site. It has the following fields: {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 15%" | '''Name ''' | style="vertical-align: top; width: 25%" | SHORT_STRING<br /> | style="vertical-align: top" | Unique group name |- | style="vertical-align: top; width: 15%" | '''Managers<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users<br /> | style="vertical-align: top" | group managers |- | style="vertical-align: top; width: 15%" | '''Users<br />''' | style="vertical-align: top; width: 25%" | REFERENCE to users | style="vertical-align: top" | group members |- | style="vertical-align: top; width: 15%" | '''Active''' | style="vertical-align: top; width: 25%" | INT<br /> | style="vertical-align: top" | obsolete groups marked as ‘0’, valid groups as ‘1’ |} <br /> "Request" record type has AssignedToGroup field (reference to "AssignmentGroups"). <br /> Request assigned to a Group first, then the Group Manager will assign it to somebody in the team. <br /> If we would like to notify the Group Managers about new request that has been assigned to the Team, <br /> we could set Email Notification Rule's "To:" field to the following value: <br /> SQL(" <source lang="sql"> SELECT T3.email FROM parent_child_links T1, fielddef T2, users T3, assignmentgroups T4 WHERE T1.parent_dbid = T4.dbid AND T1.child_dbid = T3.dbid AND T1.parent_fielddef_id = T2.id AND T2.name = 'Managers' AND T4.name = '${AssignedToGroup}' </source> ")''<br /> ===Functions=== '''function_name(parameter [, paramater1 …])'''<br /> Function name is a name of build-in, pre-defined or user-defined function. Spaces between function name and '''(''' symbol are not allowed. <br /> Parameter list is a comma-separated list of:<br /> * variables, * functions or SQL queries, * single-quoted strings, * double quoted strings with variables, functions, etc. * expressions * numeric constants Scalar value expected as function's return value. ====Function name lookup order==== * check a database property with the same name. ** If found, property value assumed to be a valid Perl-syntax code, that will be executed as function. ** Function parameters are passed as "@_" array to the function. ** $entity global variable available in function. <br /> Return value becomes function result. * check predefined functions * function name is assumed to be a Perl function. '''Examples:''' * Limit Subject line to 100 characters (Perl buld-in function "substr" is used): <source lang="perl"> substr( "some subject line with $parameters", 0, 100) </source> * Condition function:<br /> <source lang="perl"> IF($attempt > 0, 1, -1 ) </source> * Check whether "Description" field was updated during action and trigger a notification (an alternative way) :Notification Rule Condition filed: <source lang="perl"> IsFieldUpdatedThisAction('Description') != 0 </source> :Property "IsFieldUpdatedThisAction" contains the following code: <source lang="perl"> my ($name) = @_; my $result = 0 ; eval { my $fields = $entity->GetFieldsUpdatedThisAction(); $result = 1 if defined( $fields->ItemByName($name) ); }; $@ = ''; return $result; </source> * Use original value of "Description" field in the mail body :Email Notification Rule "Msg_Body" field: <br /> Original Description: "RT_GetFieldOriginalValue('Description')" was changed to: "$Description" :Property "RT_GetFieldOriginalValue" contains the following code: <source lang="perl"> my ($name) = @_; my $value = ''; eval { $value = $entity->GetFieldOriginalValue($name)->GetValue(); }; $@ = ''; return $value; </source> '''Note:''' variables of CQPerlExt module in user defined functions scope can cause 'false' execution errors, because CQPerlExt objects usually do not clear $@ variable on destruction. It would be safer to destroy private objects references before leaving the function and clean $@ variable to avoid the problem, for example: <source lang="perl"> my $session = $entity->GetSession(); # ... <some code> $session = undef; $@ = ''; return $return_value; </source> ===Double-quoted string=== Variables, functions, SQL statements are expanded within double-quoted strings. <br /> Escape symbols are: "\n", "\r","\t", "\f", "\b", "\a" <br /> "\" symbol by the end of new lines will escape new line symbol, i.e. <br /> "\" in front of any other symbol escapes that symbol, i.e. \$, \", etc "aaa\ bbb" is equal to "aaa bbb"'' '''Examples:''' <source lang="text"> "some string here with $variable and function f1($par1, $SQL{'Statement'}, 'string') and others" </source> <br /> ===Single-quoted strings=== Single quoted strings are not expanded. Escape symbols are \\ and \'. <br /><br /> ==Conditions== Conditions are implemented in perl-like style (please check Perl manual for detailed syntax documentation).<br /> They can contain variable, single- and double-quoted strings, function and other elements described in previous section. <br /> You can group expressions with brackets ( ). <br /> <br /> ==='''Operators''' (in priority order)=== {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Operator ! style="vertical-align: top" | Comments |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>!, ~, +, -</nowiki>''' | style="vertical-align: top" | Unary operators<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>=~, !~</nowiki>''' | style="vertical-align: top" | regular expression at the right side can include modifiers (/m/i/…/) |- | style="vertical-align: top" | '''<nowiki>*, /, %, x </nowiki>'''<br /> | style="vertical-align: top" | mult, div, ... <br /> |- | style="vertical-align: top" | '''+, -, .'''<br /> | style="vertical-align: top" | plus, minus, string concatenation<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | '''gt, ge, lt, le, >, >=, <, <=''' | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''eq, ne, cmp, != , ==, <=>'''<br /> | style="vertical-align: top" | String and numeric comparison |- | style="vertical-align: top; width: 30%; text-align: center" | '''&&'''<br /> | style="vertical-align: top" | Logical AND |- | style="vertical-align: top; width: 30%; text-align: center" | '''<nowiki>||</nowiki>'''<br /> | style="vertical-align: top" | Logical OR |} '''Note:''' it has to be a space between '/' operator and operand.<br /> '''Examples:'''<br /> <source lang="perl"> ($field =~ /something/i) && ($another_field > function($param1, $param2) || $another_value) </source> <br /><br /> ==Build-in (Predefined) Functions== ===IF( <expression>, <val1>, <val2) )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<expression> ''' | style="vertical-align: top; width: 80%" | logical expression<br /> |- | style="vertical-align: top" | '''<val1>'''<br /> | style="vertical-align: top" | parameter returned if expression is true<br /> |- | style="vertical-align: top" | '''<val2>'''<br /> | style="vertical-align: top" | parameter returned if expression is false<br /> |} '''Returns:'''<br /> <val1> or <val2> depending on expression result.<br /><br /> '''Examples:''' <source lang="perl"> IF( $owner.email ne '' , $owner.email, 'administrator@email-address.net' ) </source> <br /> ===GetFieldOriginalValue(<fieldname>)=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<fieldname>''' | style="vertical-align: top; width: 80%" | ClearQuest field name |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> IF( GetFieldOriginalValue('owner') ne $owner, GetFieldOriginalValue('owner.email'), $owner.email ) </source> <br /> ===GetGroupEmailAddresses(<group> [, <group2> [, ... ]])=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<group>''' | style="vertical-align: top; width: 80%" | ClearQuest groups list |} '''Returns:'''<br /> ClearQuest field original value.<br /><br /> '''Examples:''' <source lang="perl"> GetGroupEmailAddresses( 'Admins', 'Engineering' ) </source> <br /> ===GetDateTime( [ <offset> ] )=== '''Parameters:''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ‘now’ | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus offset as date_time string in 'yyyy-mm-dd hh:mm:ss' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime()</source> | style="vertical-align: top" width="60%" | now |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime('-1d')</source> | style="vertical-align: top" width="60%" | yesterday |- | style="vertical-align: top; width: 20%" width="40%" | <source lang="perl">GetDateTime( -300 )</source> | style="vertical-align: top" width="60%" | five minutes before |} <br /> ===DateTimePlusOffset( <date_time> [, <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ''yyyy-mm-dd [hh:mm:ss]'' format |- | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from <date_time> in [+-]?[\d+][smhd]? format |} '''Returns:'''<br /> Given date plus offset as a date_time string in 'yyyy-mm-dd hh:mm:ss' format <br /><br /> '''Examples:''' <source lang="perl">DateTimePlusOffset('2000-10-01 00:01:30', '+30m')</source> Returns: ''2000-10-02 00:31:30'' <br /><br /> <source lang="perl">DateTimePlusOffset( $Eneter_Date, '3d' )</source> Returns: value of 'Enter_Date' field + 3 days.<br /> ===GetDateTimeFromTimestamp( <timestamp>)=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<timestamp> ''' | style="vertical-align: top; width: 80%" | long number of seconds since 01/01/1970 (result of time() function) |} Converts timestamp to local date/time. '''Returns:'''<br /> string in ''yyyy-mm-dd hh:mm:ss'' format '''Example:''' <source lang="perl">GateDateTimeFromTimestamp(time())</source> Returns current date <br /> ===DateTimeToDate( <date_time> )=== '''Parameters:'''<br /> {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |} Converts date/time string to date only string. <br /> '''Returns:'''<br /> Date String in ''yyyy-mm-dd'' format. <br /> ===GetDate( [ <offset> ] )=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | '''<offset> ''' | style="vertical-align: top; width: 80%" | offset from current date/time in the following format: |} General offset format: [+-]?[\d+][smhd]? <br /><br /> {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | none or ''now'' | style="vertical-align: top" | offset = 0 |- | style="vertical-align: top; width: 30%" | +1<br /> | style="vertical-align: top" | + 1 second<br /> |- | style="vertical-align: top; width: 30%" | '+5s'<br /> | style="vertical-align: top" | + 5 seconds<br /> |- | style="vertical-align: top; width: 30%" | '-2m'<br /> | style="vertical-align: top" | - 2 minutes<br /> |- | style="vertical-align: top; width: 30%" | '+10h'<br /> | style="vertical-align: top" | + 10 hours<br /> |- | style="vertical-align: top; width: 30%" | '3d'<br /> | style="vertical-align: top" | + 3 days<br /> |} '''Returns:'''<br /> Current date/time plus <offset> as a date strings in ''yyyy-mm-dd'' format '''Examples:''' {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate()</source> | style="vertical-align: top" | today |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('-1d')</source> | style="vertical-align: top" | yesterday |- | style="vertical-align: top; width: 30%" | <source lang="perl">GetDate('+1d' )</source> | style="vertical-align: top" | tomorrow |} <br /> ===DateTimeDiff( <date_time1>, <date_time2> [ , <modifier>])=== '''Parameters: ''' {| style="width: 60%; height: 60px; text-align: left" border="1" cellspacing="2" cellpadding="5" | style="vertical-align: top" | '''<date_time1>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top" | '''<date_time2>''' | style="vertical-align: top" | string in ‘yyyy-mm-dd [hh:mm:ss]’ format |- | style="vertical-align: top; width: 30%" | '''<modifier>''' | style="vertical-align: top; width: 80%" | none/’s’/’m’/’h’/’d’ |} Modifier changes returned result from difference in seconds, when it is ''s'' or absent, to minutes (''m''), hours (''h'') or days (''d''). {| style="width: 60%; text-align: left" border="1" cellspacing="2" cellpadding="5" ! style="vertical-align: top; width: 30%; text-align: center" | Modifier<br /> ! style="vertical-align: top" | result in |- | style="vertical-align: top; width: 30%; text-align: center" | undef<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 's'<br /> | style="vertical-align: top" | seconds<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'm'<br /> | style="vertical-align: top" | minutes<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'h' | style="vertical-align: top" | hours<br /> |- | style="vertical-align: top; width: 30%; text-align: center" | 'd' | style="vertical-align: top" | days<br /> |} '''Returns:'''<br /> (<date_time1> - <date_time2>) in seconds or other metrics, according to modifier: '''Example:''' <source lang="perl">DateTimeDiff( $action_date, GetDateTime(), 'd')</source> Returns a difference between $action_date field and current date/time in days.<br /><br /> = Access control = '''udb_property''' and '''Email_Notification_Rule''' records are protected using security context (udb_visibility). By default, security context field is not set, and superuser only can submit, update, or delete configuration records. You can delegate maintenance tasks by creating desirable security context records and setting PropertyDefaultSecurityGroup and NotificationDefaultSecurityGroup database properties to populate security context field automatically when records are created (records existing before setting these properties would need to be updated manually). Default security group properties also affect action permissions. {| border="1" width="100%" align="center" ! Record Type ! Action ! Permissions |- |rowspan="3"|'''udb_visibility''' | Submit | * Superuser |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''udb_property''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by PropertyDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''Email_Notification_Rule''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- |rowspan="3"|'''en_email_message''' | Submit | * Superuser * A member of group specified by EN_AdminGroup database property |- | Update | * Superuser * A member of group specified by EN_AdminGroup database property |- | Remove | * Superuser * A member of group specified by EN_AdminGroup database property |- |rowspan="5"|'''Email_Subscription''' | Submit | * Superuser * Security Administrator * Default Security context group member : (set by NotificationDefaultSecurityGroup database property) |- | Update | * Superuser * Security Administrator * Security context group member |- | Remove | * Superuser |- | Subscribe_Me | * All users |- | Unsubscribe_Me | * All users |} <BR /> Submit action can be enabled for all users by setting '''Notification_Bypass_Access_Control''' database property. <BR /> = Examples = Additional examples can be found on [[Notification_Examples | Examples]] page. [[Category:Rational]] [[Category:Email_Notification_Package]] ea6772c1a646329db59f48348d53715d1f9cd919 8 17 251 29 2013-02-01T14:52:50Z Paul 1 wikitext text/x-wiki * navigation ** mainpage|CQ Admin Home ** ClearQuest_Email_Notification_Package | Email notification package ** User_Admin_Tool | User Admin Tool for ClearQuest ** ClearQuest_Dynamic_List_Editor | Dynamic List Editor for ClearQuest ** Download | Downloads ** http://forum.cqadmin.org | Forum ** Category:Rational | Index * SEARCH * TOOLBOX * LANGUAGES 37f17c9f0ba9be0e831409b8fb91826c39541a40 8 17 252 251 2013-02-01T14:53:26Z Paul 1 wikitext text/x-wiki * navigation ** mainpage|CQ Admin Home ** ClearQuest_Email_Notification_Package | Email notification package ** User_Admin_Tool | User Admin Tool ** ClearQuest_Dynamic_List_Editor | Dynamic List Editor ** Download | Downloads ** http://forum.cqadmin.org | Forum ** Category:Rational | Index * SEARCH * TOOLBOX * LANGUAGES e273d71adf58cce0f1c5bb05aee6a8036b1c5736 278 252 2013-10-24T14:51:22Z Paul 1 wikitext text/x-wiki * navigation ** mainpage|CQ Admin Home ** ClearQuest_Email_Notification_Package | Email notification package ** User_Admin_Tool | User Admin Tool ** ClearQuest_Dynamic_List_Editor | Dynamic List Editor ** Download | Downloads ** http://forum.cqadmin.com | Forum ** Category:Rational | Index * SEARCH * TOOLBOX * LANGUAGES 2e6aacc0a039aadc9137cff66aa0edf8a334abb4 0 89 253 250 2013-02-03T16:23:59Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:ClearQuest]] [[Category:User_Admin_Tool]] 2256f1a817632e5ca3ab490d2e5165ce1d2114b9 254 253 2013-02-18T16:59:20Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> [[File:R4_Rational.jpg|right|140px]] == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:ClearQuest]] [[Category:User_Admin_Tool]] 40f9364cb103e2b186288dfdf5f19c8515fc6065 257 254 2013-04-13T17:26:11Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> <!--[[File:R4_Rational.jpg|right|140px]]--> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:ClearQuest]] [[Category:User_Admin_Tool]] e8f6495c136370e5be2bcb0c79b0c1c2add0a8e4 260 257 2013-04-15T19:42:28Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool for IBM-Rational ClearQuest'''</big> [[File:R4_Rational.jpg|right|140px]] <!-- comment --> == Overview == IBM-Rational ClearQuest is one of the greatest tools available in the IBM portfolio. It became even more valuable with introduction of the enhanced ClearQuest Web interface. Having Web based user administrating tool was a dream of ClearQuest administrators for a long time. I would like to present a Web based user administration tool that was implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on an administrator's desktop. It simplifies remote site management and adds other features that were missing in the standard User Administrator. == Ultimate Query and Search Capabilities == The User Administration tool is based on ClearQuest and utilized its powerful query and search capabilities. Finding users or groups has never been easier. The basic search can be enhanced using full-text search engine. == Customizable Defaults == The tool allows you to setup defaults for most of the User and Group record fields. For example, you can choose default authentication mechanism to be LDAP instead of ClearQuest, specify default list of User Privileges, Groups, and Database subscription to simplify your life and save your valuable time. Even new user password can be randomly generated when you use ClearQuest authentication. == Customizable Fields Validation == In addition to defaults, the tool offers enhanced validation features, and there would be no need to change schema. Most of the conditions can be specified in the database on the fly. For instance, you can check that user email is specified as an Internet email address from your company domain; use advanced validation for login name, full name, phone, etc. == Managing Users Using Profiles and Templates == Have you ever tried creating user account that has "the same rights" as another user account in the enterprise database containing thousands of users and hundreds of groups? In this case you will like this feature. Mirroring user or adding "somebody else" rights has never been easier. You need to specify other user, and the system will take care of the rest. Moreover, it allows to setup a set of template profiles or roles that can be used to expedite new users provisioning and guard you from mistakes. Setting up new "CM Manager" or "Project Admin" would take seconds. == Granular Access == In addition to the ClearQuest defined user permissions, the tool allows you to define its own equivalents. If you set up the system this way, the tool user admins would have user administration access within the User Admin Tool, but they would not be able to run the same operations using the standard user admin utility. It prevents from mistakes and unnecessary synchronizations between the databases.<br /> In addition, the tool allows you to setup group administrators, users, that are allowed to administer specific group(s) only. If you are using ClearQuest authentication, you can also safely delegate password reset rights to your first-tier helpdesk personal. == Reporting == The system provides a set of out-of-the box reports. In just few clicks you can get printable list of active users, or find out user accounts or groups that were updated since yesterday. You can also use provided report formats to build your own reports. == Audit Trail == One of the most important for account management features is audit capability. When you use User Administration Tool, you can always answer the following questions: who, when, and what. More advanced audit capabilities are based on [[ClearQuest_Email_Notification_Package | Email Notification package]], and can be turned on at any time, and in case if it is not enough, you can use Audit Trail package to enhance audit capabilities. == Email Notifications == The system offers customizable and ultimately flexible notification rules based on [[ClearQuest_Email_Notification_Package | Email Notification package]] for IBM-Rational ClearQuest. Configurable email formats, recipients, and advanced conditions allows you to implement any possible notification scenario. == Additional Information== The following links could be useful * [[User_Admin_Tool_Installation | Installing User Administration Tool]] * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [[Download | Downloads]] * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:ClearQuest]] [[Category:User_Admin_Tool]] e9e0cc33c86df8b65098c6ad5fab740f041f5fc1 0 2 255 228 2013-02-18T17:31:02Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and adds other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 48daa07e64b60949d07494beb4060ba556df0138 256 255 2013-02-18T17:31:38Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and adds other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''Email Notification Package is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 7cd98d4e638d8dceaca37fd775e52a967736c754 259 256 2013-04-15T19:41:47Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] has been released.''' : The tool is implemented on IBM-Rational ClearQuest platform and does not require ClearQuest installation on administrator's desktop. It simplifies site management and adds other valuable features, such as ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. * '''IBM-Rational VoiCE 2011''' : ClearQuest Email Notification package was presented at IBM-Rational VoiCE 2011 conference in Reno, NV ([http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf presentation]) <br /> == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 0e95ed8f25be52f6881d799de86e265f3ca68e0c 264 259 2013-06-06T19:42:18Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. It is powered by [http://www.mediawiki.org MediaWiki] and opened for everyone. If you would like to contribute your materials, please feel free to do it. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. The User Administration tool simplifies site management and adds other valuable features, such as Web-based user administration, ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] cab3e48609d743818d9c783f9eeebbdd9c276bd4 277 264 2013-10-20T14:09:40Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. The User Administration tool simplifies site management and adds other valuable features, such as Web-based user administration, ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.org/ http://forum.cqadmin.org/] <br /><br /> [[Category:Rational]] 39d3df9f9b9a5b2629673cf4793784cdd87f9e8b 279 277 2013-10-24T14:51:50Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. The User Administration tool simplifies site management and adds other valuable features, such as Web-based user administration, ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.com/ http://forum.cqadmin.com/] <br /><br /> [[Category:Rational]] 886cd8ca2bd0a0225182e7790258cddd24cfed57 280 279 2013-11-05T12:34:03Z Paul 1 wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. The User Administration tool simplifies site management and adds other valuable features, such as Web-based user administration, ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is officially [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support are currently offered, starting with '''free''' community support at [http://forum.cqadmin.com http://forum.cqadmin.com]. Consulting services are also available. == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.com/ http://forum.cqadmin.com/] <br /><br /> [[Category:Rational]] a39423e79f7d97846aebd84e1a779da51daa38bd 281 280 2016-12-29T02:55:04Z Paul 1 /* Latest news */ wikitext text/x-wiki <big>'''Rational Administrators'''</big> This site was created to provide tools, information, and share experience that might be useful for Rational tools administrators. == Latest news == * '''The [[User_Admin_Tool | User Administration Tool for IBM-Rational ClearQuest]] is "Ready for IBM-Rational Software"''' : The User Administration Tool was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. It met the requirements for the IBM Software Delivery Platform level of the program. The User Administration tool simplifies site management and adds other valuable features, such as Web-based user administration, ultimate query and search capabilities, customizable defaults and validations, user profiling and templates, granular access, reporting and audit, email notifications and more. * '''[[ClearQuest_Email_Notification_Package | Email Notification Package]] is "Ready for IBM-Rational Software"''' : Email Notification package was successfully validated to the requirements of <i style="color:blue;">Ready for IBM Rational Software</i>. The package met the requirements for the IBM Software Delivery Platform level of the program. * '''Commercial Support''' : ClearQuest Email Notification package is supported via '''free''' community at [http://forum.cqadmin.com http://forum.cqadmin.com]. == Resources == * [[ClearQuest_Email_Notification_Package | Email Notification Package]] for IBM-Rational ClearQuest. : If you would like to use flexible notification rules, reliable delivery, sending HTML emails with rich text, fonts, and colors, configuring reminders, and many other features, you might like the package. * [[User_Admin_Tool | User Administration Tool]] for IBM-Rational ClearQuest. : It simplifies site management and adds other valuable features, such as customizable defaults and validations, user profiling and templates, reporting and audit, email notifications and more. * [[ClearQuest_Dynamic_List_Editor | Dynamic List Editor]] for IBM-Rational ClearQuest. : Would you like to administer Dynamic Lists via the ClearQuest Web client? You might consider using the editor. * '''Support forum''' : Support forum is available now. Please do not hesitate to ask questions or share your experience. : [http://forum.cqadmin.com/ http://forum.cqadmin.com/] <br /><br /> [[Category:Rational]] 0066c05c5a37583de4f0aa8455b66b835146562c 0 5 258 230 2013-04-13T17:26:35Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> <!--[[File:R4_Rational.jpg|right|140px]]--> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Support == : ClearQuest Email Notification package is [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html officially supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 5a1678a7006d98a44aa7cc4d66402c3c351405d0 261 258 2013-04-15T19:43:17Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> [[File:R4_Rational.jpg|right|140px]] <!--[[File:R4_Rational.jpg|right|140px]]--> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. == Support == : ClearQuest Email Notification package is [http://store.cqadmin.com/index.php/clearquest/cq-email-notification/email-notification-package-support.html officially supported] by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 9de29d609c6b98a32234a812a9385f97621540eb 288 261 2017-04-24T03:37:30Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Email Notification Package'''</big> [[File:R4_Rational.jpg|right|140px]] <!--[[File:R4_Rational.jpg|right|140px]]--> Created by ClearQuest admin for ClearQuest admins. == Email Notification Package == It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it. The package was initially released in 2004, and presented on [http://cqadmin.org/data/CCMA43.pdf RUC 2006] and [http://cqadmin.org/data/Reno_VoiCE-ClearQuest_Email.pdf IBM VoiCE 2011]. Here is a quick overview of some of the features. === Centralized configuration and maintenance === Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing. === Reliable delivery/Message Queue === If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package '''Light''', '''Deferred''' (default), and '''Queue'''. In case of '''Light''' delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only. '''Deferred''' delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed. In case of '''Queue''' delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server. You can find out more about delivery modes [[ClearQuest_Email_Notification_Package_Delivery_Mode | here]]. === Email Message Log/Audit trail === In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest. Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary. === Customizable message envelope and body === You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results. For example, you configured subject in your email notification rule as: Defect $ID has been $State and subject in the generated email message might look like Subject: Defect RATL0000001 has been closed You can also use html emails with rich formatting, colors, embedded images, links, etc.<br /><br /> [[File:sample_email.png|border]] === Configurable email message priority === Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email. === Additional header information === It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information. === Notification conditions === Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns. === Message sender and reply-to address === You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails. === Site-specific settings in Multisited environment === If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site. === Password authentication with SMTP relay === Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database === Reminders === Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it [[Timed_Notification | Timed Notification]]. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action. === Email Notification Subscription === You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional '''EmailSubscription''' package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check [[ClearQuest_Email_Subscription | Email Subscription]] page for details. == Getting Started == Would you like to try it? Then, '''create a backup of your schema and user database''', or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only. # [[Download | Download]] the package. # [[Package_installation | Install it]]. # Create your [[EmailNotification_Creating_First_Notification_Rule | first notification rule]] == Additional Information == # It could be useful to read [[Package_configuration | package configuration guide]] and # [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] # Please check [[Notification_Examples | Examples]] and # [http://cqadmin.org/data/CCMA43.pdf Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications] presentation # [[Timed_Notification | Reminders / Timed Notifications]] # [[ClearQuest_Email_Subscription | End users self-subscription to email notifications]] # If you have questions or problems, welcome to the [http://forum.cqadmin.org/ support forum] == License == The ''ClearQuest Email Notification Package'' is licensed under the ''GNU Lesser General Public License'' (AKA, the "LGPL"), Version 2.1, February, 1999. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 30a3e04135bb43271f963251988f43d916d4da4a 0 90 262 2013-06-02T10:19:07Z Paul 1 Created page with "'''EmailNotification package Delivery Service''' The service performs centralized email delivery for ClearQuest user databases utilizing [[ClearQuest_Email_Notification_Packag..." wikitext text/x-wiki '''EmailNotification package Delivery Service''' The service performs centralized email delivery for ClearQuest user databases utilizing [[ClearQuest_Email_Notification_Package | Email Notification]] package in '''Queue''' mode. It features: * Servicing multiple user databases and multiple connections (dbsets) * Performing scheduled delivery with configured interval and offset. * Operating in console mode, or working as a service. * Sending emails via secure connection using SMTP over SSL or STARTTLS extension. * Supporting login, digest, and NTLM authentication mechanisms. * Preventing user credentials from exposure by encrypting them in the configuration file. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 46b679d4616bb26fa539c7ad01c1c7b62d8d6a8c 271 262 2013-06-22T22:18:10Z Paul 1 wikitext text/x-wiki '''EmailNotification package Delivery Service''' The service performs centralized email delivery for ClearQuest user databases utilizing [[ClearQuest_Email_Notification_Package | Email Notification]] package in '''Queue''' mode. It features: * Servicing multiple user databases and multiple connections (dbsets) * Performing scheduled delivery with configured interval and offset. * Operating in console mode, or working as a service. * Sending emails via secure connection using SMTP over SSL or STARTTLS extension. * Supporting login, digest, and NTLM authentication mechanisms. * Preventing user credentials from exposure by encrypting them in the configuration file. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] ff98a735232bd980477809e103918df15fcaf6cd 272 271 2013-06-22T22:21:24Z Paul 1 wikitext text/x-wiki '''EmailNotification package Delivery Service''' ClearQuest Email Service performs centralized email delivery for ClearQuest user databases utilizing [[ClearQuest_Email_Notification_Package | Email Notification]] package in '''Queue''' mode. <br /> It features: * Servicing multiple user databases and multiple connections (dbsets) * Performing scheduled delivery with configured interval and offset. * Operating in console mode, or working as a service. * Supporting login, digest, and NTLM authentication mechanisms. * Sending emails via secure connection using SMTP over SSL or STARTTLS extension. * Preventing user credentials from exposure by encrypting them in the configuration file. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 0782a5c505aa4faa0c373e6a02e8ad7210da37d8 273 272 2013-06-22T22:53:43Z Paul 1 wikitext text/x-wiki '''EmailNotification Package Delivery Service''' ClearQuest Email Service performs centralized email delivery for ClearQuest user databases utilizing the [[ClearQuest_Email_Notification_Package | Email Notification]] package in the '''Queue''' mode. <br /> It features: * Servicing multiple user databases and multiple connections (dbsets) * Performing scheduled deliveries with a configured interval and offset. * Operating in console mode or working as a service. * Supporting login, digest, and NTLM authentication mechanisms. * Sending emails via a secure connection using SMTP over SSL or STARTTLS extension. * Preventing user credentials from exposure by encrypting them in the configuration file. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] e78c658fe6a07ab8a407b245e4b33b9d0db6a60a 274 273 2013-06-22T23:18:57Z Paul 1 wikitext text/x-wiki '''EmailNotification Package Delivery Service''' ClearQuest Email Service performs centralized email delivery for ClearQuest user databases utilizing the [[ClearQuest_Email_Notification_Package | Email Notification]] package in the '''Queue''' mode. <br /> It features: * Servicing multiple user databases and multiple connections (dbsets) * Performing scheduled deliveries with a configured interval and offset. * Operating in console mode or working as a service. * Supporting login, digest, and NTLM authentication mechanisms. * Sending emails via a secure connection using an SMTP over SSL or STARTTLS extension. * Preventing user credentials from exposure by encrypting them in the configuration file. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 23662bb42143d3c2656d4849997c9c4e71c1a679 0 91 263 2013-06-02T10:42:11Z Paul 1 Created page with "'''Email Notification Package Delivery Service Command Line''' '''Usage:''' cqemail [options] command {| class="wikitable" cellpadding="10" ! align="center"| Command ! Descr..." wikitext text/x-wiki '''Email Notification Package Delivery Service Command Line''' '''Usage:''' cqemail [options] command {| class="wikitable" cellpadding="10" ! align="center"| Command ! Description |- |'''once''' |Query databases for eligible email messages, attempt delivery, and exit. It was a default behavior of the Email Delivery Script. |- |'''run''' |Run delivery attempts on defined schedule. Default schedule is to make delivery attempt every five minutes with 0 second offset from the beginning on the hour. It can be overridden by setting "interval" and "offset" parameters in the configuration file, or by correspondent command line options. |- |'''save-options''' |Save options given as command line parameters in the configuration file. |- |'''encrypt-passwords''' |Encrypt clear text password in the configuration file. All passwords in the configuration file must be in clear-text before running this command. It does not check if the password already encrypted or not. |- |'''configure''' |Run configuration graphical user interface. |- |} <br /> {| class="wikitable" cellpadding="10" ! align="center"| Option ! Description |- | -h, --help |Print help message. |- | -V, --version |Print version information. |- | -C, --config <file> |Use an alternative configuration file given as <file>. Default configuration file name is config/config.xml. |- | -u, --login <login> |ClearQuest login name. Overrides login name provided in the configuration file. |- | -p, --password <password> |ClearQuest password. Overrides user password specified in the configuration file. |- | -db, --database <database> |ClearQuest database name. Overrides dbset options set in the configuration file. |- | -dbs, --dbset <dbset> |ClearQuest connection name (dbset). Overrides dbset set in the configuration file |- | --localconfig |Use local configuration file for the email notification settings. When set in command line or in the configuration file, SMTP server name, port, authentication credential and connection settings retrieved from the configuration file. When is not set (or set to "false" in the configuration file), ClearQuest user database properties are queried first. It was a default behavior for the email notification package delivery script. |- | -L, --logfile <file> |Use alternative log file name (default is log/notification.log) |- | --loglevel <LEVEL> |Specify desirable log level. (one of the following: ALL SEVERE WARNING INFO FINE FINER FINEST). |- | --debug |Turn on debug output. |- | -v, --verbose |Turn on console output |- | --interval <seconds> |Specify scheduled run interval in seconds. Default is 300 – every 5 minutes. |- | --offset <seconds> |Specify desirable offset of the scheduled execution from the beginning of the hour. Default is 0. It can be used to schedule email delivery from multiple hosts for redundancy and avoid racing conditions. For instance, you can run delivery every 5 minutes on host1 and host2, and use offset 150 (2.5 minutes) on one of them. In this case host1 runs delivery at hh:00:00, hh:05:00, hh:10:00, hh:15:00 ... and host2 at hh:02:30, hh:07:30, hh:12:30, hh:17:30 ... |- |} [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] fe4b0e542a245bf3da413aa21ca66efa2c425912 265 263 2013-06-07T12:28:37Z Paul 1 Paul moved page [[Delivery Service Command Line]] to [[Email Notification Service Command Line]] without leaving a redirect wikitext text/x-wiki '''Email Notification Package Delivery Service Command Line''' '''Usage:''' cqemail [options] command {| class="wikitable" cellpadding="10" ! align="center"| Command ! Description |- |'''once''' |Query databases for eligible email messages, attempt delivery, and exit. It was a default behavior of the Email Delivery Script. |- |'''run''' |Run delivery attempts on defined schedule. Default schedule is to make delivery attempt every five minutes with 0 second offset from the beginning on the hour. It can be overridden by setting "interval" and "offset" parameters in the configuration file, or by correspondent command line options. |- |'''save-options''' |Save options given as command line parameters in the configuration file. |- |'''encrypt-passwords''' |Encrypt clear text password in the configuration file. All passwords in the configuration file must be in clear-text before running this command. It does not check if the password already encrypted or not. |- |'''configure''' |Run configuration graphical user interface. |- |} <br /> {| class="wikitable" cellpadding="10" ! align="center"| Option ! Description |- | -h, --help |Print help message. |- | -V, --version |Print version information. |- | -C, --config <file> |Use an alternative configuration file given as <file>. Default configuration file name is config/config.xml. |- | -u, --login <login> |ClearQuest login name. Overrides login name provided in the configuration file. |- | -p, --password <password> |ClearQuest password. Overrides user password specified in the configuration file. |- | -db, --database <database> |ClearQuest database name. Overrides dbset options set in the configuration file. |- | -dbs, --dbset <dbset> |ClearQuest connection name (dbset). Overrides dbset set in the configuration file |- | --localconfig |Use local configuration file for the email notification settings. When set in command line or in the configuration file, SMTP server name, port, authentication credential and connection settings retrieved from the configuration file. When is not set (or set to "false" in the configuration file), ClearQuest user database properties are queried first. It was a default behavior for the email notification package delivery script. |- | -L, --logfile <file> |Use alternative log file name (default is log/notification.log) |- | --loglevel <LEVEL> |Specify desirable log level. (one of the following: ALL SEVERE WARNING INFO FINE FINER FINEST). |- | --debug |Turn on debug output. |- | -v, --verbose |Turn on console output |- | --interval <seconds> |Specify scheduled run interval in seconds. Default is 300 – every 5 minutes. |- | --offset <seconds> |Specify desirable offset of the scheduled execution from the beginning of the hour. Default is 0. It can be used to schedule email delivery from multiple hosts for redundancy and avoid racing conditions. For instance, you can run delivery every 5 minutes on host1 and host2, and use offset 150 (2.5 minutes) on one of them. In this case host1 runs delivery at hh:00:00, hh:05:00, hh:10:00, hh:15:00 ... and host2 at hh:02:30, hh:07:30, hh:12:30, hh:17:30 ... |- |} [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] fe4b0e542a245bf3da413aa21ca66efa2c425912 0 92 266 2013-06-07T12:34:08Z Paul 1 Created page with "'''EmailNotification Service Configuration File''' <source lang="xml"> <?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuration> <!-- ClearQuest login and pa..." wikitext text/x-wiki '''EmailNotification Service Configuration File''' <source lang="xml"> <?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuration> <!-- ClearQuest login and password cleartext password must be encrypted using "encrypt" command --> <login>admin</login> <password>unencrypted_password</password> <!-- DBSets configured for email notification --> <dbsets> <!--each connection starts with <dbset> tag --> <dbset> <!--connection name (dbset)--> <name>ClearQuest Connection Name</name> <!-- dbset specific credentials can be specified here. It would override global settings password can be provided as clear text and encrypted using “encrypt” command. <login>connection-specific-login-name</login> <password>connection-specific-password</password> --> <!-- all user databases --> <databases> <database>DB1</database> <database>DB2</database> </databases> </dbset> <dbset> <name>Another ClearQuest DBSet</name> <databases> <database>DB3</database> </databases> </dbset> </dbsets> <!--additional configuration options Logfile – alternative log file name--> <logfile>new_log_file_name</logfile> <!-- Log level – desirable logging level --> <loglevel>ALL</loglevel> <!-- debug – turn on debug output --> <debug>true</debug> <!-- verbose – turn on console output --> <verbose>true</verbose> <!-- Local configuration flag when set to "false" email settings are retrieved from the ClearQuest database --> <localconfig>false</localconfig> <!-- example of the local email settings <localconfig>true</localconfig> email host – SMTP server name. It might include port number. <email_host>hostname:port</email_host> Alternatively, port number can be specified as <mail.smtp.port>port</mail.smtp.port> Authentication credentials. Password can be provided as clear text and encrypted using “encrypt” command. <email_login>loginname</email_login> <email_password>password</email_password> turn on STARTTLS on smtp connection: <mail.smtp.starttls>true</mail.smtp.starttls> trust particular host self-signed or invalid certificate <mail.smtp.ssl.trust>my.host.name</mail.smtp.ssl.trust> use SSL: <email_use_ssl>true</email_use_ssl> --> </configuration> </source> [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] abfa3d4f3e582d1e47c3ca39ad53a16bb0dbed60 275 266 2013-08-29T20:00:53Z Paul 1 wikitext text/x-wiki '''EmailNotification Service Configuration File''' <source lang="xml"> <?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuration> <!-- ClearQuest login and password cleartext password must be encrypted using "encrypt" command --> <login>admin</login> <password>unencrypted_password</password> <!-- DBSets configured for email notification --> <dbsets> <!--each connection starts with <dbset> tag --> <dbset> <!--connection name (dbset)--> <name>ClearQuest Connection Name</name> <!-- dbset specific credentials can be specified here. It would override global settings password can be provided as clear text and encrypted using “encrypt” command. <login>connection-specific-login-name</login> <password>connection-specific-password</password> --> <!-- all user databases --> <databases> <database>DB1</database> <database>DB2</database> </databases> </dbset> <dbset> <name>Another ClearQuest DBSet</name> <databases> <database>DB3</database> </databases> </dbset> </dbsets> <!-- scheduled execution parameters by default the service queries database every 5 minutes (30 seconds) with 0 seconds offset from the beginning of the hour <interval>300</interval> <offset>0</offset> --> <!--additional configuration options Logfile – alternative log file name--> <logfile>new_log_file_name</logfile> <!-- Log level – desirable logging level --> <loglevel>ALL</loglevel> <!-- debug – turn on debug output --> <debug>true</debug> <!-- verbose – turn on console output --> <verbose>true</verbose> <!-- Local configuration flag when set to "false" email settings are retrieved from the ClearQuest database --> <localconfig>false</localconfig> <!-- example of the local email settings <localconfig>true</localconfig> email host – SMTP server name. It might include port number. <email_host>hostname:port</email_host> Alternatively, port number can be specified as <mail.smtp.port>port</mail.smtp.port> Authentication credentials. Password can be provided as clear text and encrypted using “encrypt” command. <email_login>loginname</email_login> <email_password>password</email_password> turn on STARTTLS on smtp connection: <mail.smtp.starttls>true</mail.smtp.starttls> trust particular host self-signed or invalid certificate <mail.smtp.ssl.trust>my.host.name</mail.smtp.ssl.trust> use SSL: <email_use_ssl>true</email_use_ssl> --> </configuration> </source> [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] c6d3873f8165c542a15293b287df8e989ec73b6f 276 275 2013-08-29T20:03:27Z Paul 1 wikitext text/x-wiki '''EmailNotification Service Configuration File''' <source lang="xml"> <?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuration> <!-- ClearQuest login and password cleartext password must be encrypted using "encrypt" command --> <login>admin</login> <password>unencrypted_password</password> <!-- DBSets configured for email notification --> <dbsets> <!--each connection starts with <dbset> tag --> <dbset> <!--connection name (dbset)--> <name>ClearQuest Connection Name</name> <!-- dbset specific credentials can be specified here. It would override global settings password can be provided as clear text and encrypted using “encrypt” command. <login>connection-specific-login-name</login> <password>connection-specific-password</password> --> <!-- all user databases --> <databases> <database>DB1</database> <database>DB2</database> </databases> </dbset> <dbset> <name>Another ClearQuest DBSet</name> <databases> <database>DB3</database> </databases> </dbset> </dbsets> <!-- scheduled execution parameters by default the service queries the databases every 5 minutes (30 seconds) with 0 seconds offset from the beginning of the hour <interval>300</interval> <offset>0</offset> --> <!--additional configuration options Logfile – alternative log file name--> <logfile>new_log_file_name</logfile> <!-- Log level – desirable logging level --> <loglevel>ALL</loglevel> <!-- debug – turn on debug output --> <debug>true</debug> <!-- verbose – turn on console output --> <verbose>true</verbose> <!-- Local configuration flag when set to "false" email settings are retrieved from the ClearQuest database --> <localconfig>false</localconfig> <!-- example of the local email settings <localconfig>true</localconfig> email host – SMTP server name. It might include port number. <email_host>hostname:port</email_host> Alternatively, port number can be specified as <mail.smtp.port>port</mail.smtp.port> Authentication credentials. Password can be provided as clear text and encrypted using “encrypt” command. <email_login>loginname</email_login> <email_password>password</email_password> turn on STARTTLS on smtp connection: <mail.smtp.starttls>true</mail.smtp.starttls> trust particular host self-signed or invalid certificate <mail.smtp.ssl.trust>my.host.name</mail.smtp.ssl.trust> use SSL: <email_use_ssl>true</email_use_ssl> --> </configuration> </source> [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 548b77847b68098a6edb6618cd464936620c5386 0 69 267 244 2013-06-16T11:46:09Z Paul 1 wikitext text/x-wiki <big>'''User Administration Tool Installation'''</big> == Planing the Installation == User Administration Tool for IBM-Rational ClearQuest is a ClearQuest database. The installer will add a custom schema to your schema repository, create user database associated with the schema, and load all data. Before you proceed, you need to collect: * Physical Database information of empty database (DB vendor, server, database name, database user account, and connect options). The database needs to be created in advance (unless you are going to use Microsoft Access). * Email notification settings - SMTP server name and email user credentials (if password authentication is required with SMTP relay). You can check [[Package_configuration | Email Notification Package Configuration]] page for additional information. * Obtain local administrative rights on the machine where you are going to perform the installation. * Create (or use an existing) ClearQuest account with Super User right that will be used for user account management. It is recommended to use ClearQuest authentication for the account to avoid problems related to password expiration. == Backup Schema Repository Database == It is always a good idea to create a backup before you making any change to the schema repository to roll back the change if necessary, and I strongly recommend to install the tool in your testing environment first: you would be able to validate that it is compatible with your environment and database vendor. It would minimize risks associated with deployment of the tool in your production environment later. == Installing User Admin Tool == You can run installation of the User Administration tool on any machine that has IBM-Rational ClearQuest installed and ClearQuest connection configured. <br />Download and run "setup.exe", accept license agreement. If "Run User Administration DB Setup Wizard" task is selected, user administration tool setup will be launched automatically. You can setup user administration database later by using "DB Setup" wizard located in the programs menu (Programs -> CQAdmin -> DB Setup). <br />Login to the ClearQuest using connection (dbset) that you would like to enable for user administration using Super User account you created on the "planning..." step. [[File:user_admin_install_login.png|none]] <br />Provide required information to create ClearQuest User Administration database. Depending on your database vendor and environment, you might need to provide additional connection options. Please check ClearQuest administration manual for details. If you aborted the installation for any reason after user database was created, you would be allowed to select user database created earlier instead of creating a new one. [[File:user_admin_db_settings.png|none]] <br />Verify that you entered all information and click on "Create DB" button. The installer will start creating user database and importing all user data. There is no progress indicator, please be patient. Depending on database server load and number of user accounts the initial load might take significant time. For example, in my local environment it takes about 15 minutes to load 3000 users and groups. When user database is created and data import is completed, the installer will offer you to configure email notification setting. Please provide required information and save settings. The installer will validate SMTP server connectivity. [[File:user_admin_en_config.png|none]] <br />It is the last step in the installation procedure, and no error occurred, you should receive the following confirmation. [[File:user_admin_install_completed.png|none]] <br />Congratulations! You have completed your installation. Log in to the ClearQuest database you created and you can start using it immediately. == Additional Information== The following links could be useful * [[User_Admin_Tool_Configuration | Configuring User Administration Tool]] * [[Managing_ClearQuest_Users | Managing ClearQuest Users]]. * [http://forum.cqadmin.org/ Support forum] [[Category:Rational]] [[Category:User_Admin_Tool]] c4dc6a12eda34fbd29752ffebe4e877c73a4ca08 0 93 268 2013-06-16T18:16:38Z Paul 1 Created page with "<big>'''ClearQuest Dynamic List Editor'''</big> === Manual Setup of a ClearQuest Schema === It is highly recommended to test the procedure in your development environment, an..." wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> === Manual Setup of a ClearQuest Schema === It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start. ==== Schema Integration ==== The schema integration, "Dynamic_List_Editor.txt", is locate in the "data" folder of the installation directory. It is a text file that can be easily scanned or inspected. ==== Apply Integration to ClearQuest Schema ==== * Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database. * Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted. * Import integration using the "cqload importintegration" command. For example: cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt "" * Verify that the schema update was imported and no issues were detected. [[File:cqload_completed.png|center]] ==== Upgrade User Database ==== Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database). [[File:upgrade_db.png|center]] Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully. [[File:upgrade_db_completed.png|center]] ==== Import First Dynamic List ==== The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit a new record of the "Dynamic_List" type: [[File:Submit_Dynamic_List_1.png|center]] Select one of the list names from the "Name" drop-down list. [[File:Submit_Dynamic_List_2.png|center]] Dynamic list values will be populated automatically. [[File:Submit_Dynamic_List_3.png|center]] click "Save" to commit the record to the database ==== Creating Dynamic List Administration Query ==== Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu. [[File:Dynamic_List_Query _1.png|center]] Select "Dynamic_Query" as a record type [[File:Dynamic_List_Query _2.png|center]] Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query. [[File:Dynamic_List_Query _3.png|center]] ==== Importing Dynamic Lists ==== Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action. [[File:Dynamic_List_Sync_1.png|center]] The action syncs ClearQuest records with the correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. [[File:Dynamic_List_Sync_2.png|center]] If no error occurred, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with their proper content are loaded. [[File:Dynamic_List_Sync_3.png|center]] == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] e22e904c80c74fc21d863714d4354b245fbc9c02 0 45 269 245 2013-06-16T18:25:20Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically. == Installation Instruction == '''Please create a backup of schema and user databases before the installation.'''<br /> The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Automatic Install === * Unpack the distribution to your local or network drive (you cannot start the installation from a network share using UNC path) * Launch "install.bat" in the root of the distribution * Accept license agreement * Provide administrative user credentials, ClearQuest connection, database name, and click on "Connect" When installation is completed, login to the user database and run "Public Queries/Administration/Dynamic_Lists" query to verify Dynamic list data. You can start using the tool immediately. === Manual Install === You can install the Editor manually: [[ClearQuest_Dynamic_List_Editor_ManualSetup | Manual Setup ]]. == Administering Dynamic Lists == When installation is completed, ClearQuest administrators can start using ClearQuest client to query Dynamic_Lists records to modify the content of the linked dynamic lists. If you used installation wizard, "Dynamic Lists" query is located in the "Administration" folder of the "Public Queries" workspace: [[File:Dynamic_List_Sync_3.png|center]] Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves the content of the current ClearQuest records into a correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source. |- | SyncAllLists | Utilities / Script | Super User | This action syncs ClearQuest records with their correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 8eb7a11dbc8cbddfb2a4500c4f800c9e8aab6f1b 270 269 2013-06-16T18:30:52Z Paul 1 wikitext text/x-wiki <big>'''ClearQuest Dynamic List Editor'''</big> Created by ClearQuest admin for ClearQuest admins. = Dynamic List Editor = This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required. In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type. [[File:Dynamic_List_Editor.png|center]] Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically. == Installation Instruction == '''Please create a backup of schema and user databases before the installation.'''<br /> The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients. === Automatic Install === * Download the distribution to your local or network drive * Launch "setup.exe" * Accept license agreement * When configuration wizard is launched, provide administrative user credentials, ClearQuest connection, database name, and click on "Connect" (or, you can cancel ClearQuest schema configuration wizard and configure selected database later). When installation is completed, login to the user database and run "Public Queries/Administration/Dynamic_Lists" query to verify Dynamic list data. You can start using the tool immediately. === Manual Install === You can install the Editor manually: [[ClearQuest_Dynamic_List_Editor_ManualSetup | Manual Setup ]]. == Administering Dynamic Lists == When installation is completed, ClearQuest administrators can start using ClearQuest client to query Dynamic_Lists records to modify the content of the linked dynamic lists. If you used installation wizard, "Dynamic Lists" query is located in the "Administration" folder of the "Public Queries" workspace: [[File:Dynamic_List_Sync_3.png|center]] Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration: {| class="wikitable" ! Action Name ! Action Type ! Access Control ! Description |- | Submit | Submit | Super User | Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once. |- | Update | Modify | Super User, Dynamic List Admins | Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well. |- | Delete | Utilities / Delete | Super User | This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade. |- | LoadList | Utilities / Script | Super User, Dynamic List Admins | Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it. |- | SaveList | Utilities / Script | Super User, Dynamic List Admins | Save List action saves the content of the current ClearQuest records into a correspondent dynamic list. |- | SaveAllLists | Utilities / Script | Super User, Dynamic List Admins | Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source. |- | SyncAllLists | Utilities / Script | Super User | This action syncs ClearQuest records with their correspondent dynamic lists: * when the ClearQuest record already exists, its content is updated from the dynamic list * when the ClearQuest record does not exist, a new record is created * when a dynamic list for the existing ClearQuest record does not exist, the record is deleted. |} == Dynamic Lists Caching == In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification. == Support == : ClearQuest Dynamic List Editor is supported by [http://cqadmin.com CQAdmin, inc]. Three levels or support agreement are currently offered, starting with '''free''' community support at [http://forum.cqadmin.org http://forum.cqadmin.org]. Consulting services are also available. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Dynamic_List_Editor]] 67bc622a2fe1c26609d7f6836ac31e46f84740c5 0 6 282 247 2017-04-24T03:29:26Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://cqadmin.org/data/emailnotificationpackagesetup.exe this link] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://cqadmin.org/data/cqdynamiclisteditor_1.exe this kink]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [[http://cqadmin.org/data/cquseradmintoolsetup.exe this kink]. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] 30096e8df83033b2e6419dcfe720ad168db7da6b 283 282 2017-04-24T03:29:47Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://cqadmin.org/data/emailnotificationpackagesetup.exe this link] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://cqadmin.org/data/cqdynamiclisteditor_1.exe this kink]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [[http://cqadmin.org/data/cquseradmintoolsetup.exe this link]. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] dde0e9ac7b950b4b499782860d3b385bef1fc96f 284 283 2017-04-24T03:30:16Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://cqadmin.org/data/emailnotificationpackagesetup.exe this link] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://cqadmin.org/data/cqdynamiclisteditor_1.exe this link]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [[http://cqadmin.org/data/cquseradmintoolsetup.exe this link]. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] c93de79cc5dc2ea1b55108793dec16d2c4b8471e 285 284 2017-04-24T03:30:42Z Paul 1 wikitext text/x-wiki <big>'''Downloads'''</big> == ClearQuest Email Notification Package == Please visit [[Package_installation | installation]] and [[Package_configuration | configuration]] pages for detailed instructions.<br /> The package and supplementary scripts are available now at [http://cqadmin.org/data/emailnotificationpackagesetup.exe this link] <br /><br /> == Dynamic List Editor for IBM-Rational ClearQuest == Please check the [[ClearQuest_Dynamic_List_Editor | documentation]] page for details.<br /> The distribution is available at [http://cqadmin.org/data/cqdynamiclisteditor_1.exe this link]. <br /><br /> == User Administration Tool for IBM-Rational ClearQuest == Please check the [[User_Admin_Tool_Installation | installation]] and [[User_Admin_Tool_Configuration | configuration]] pages for details.<br /> The distribution is available at [http://cqadmin.org/data/cquseradmintoolsetup.exe this link]. [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] [[Category:Dynamic_List_Editor]] [[Category:User_Admin_Tool]] 1b58764e02f230f4200ddf906d4f1e0a61240be4 0 44 286 241 2017-04-24T03:35:18Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. <br /> == Other Notes == === Supplementary scripts === Supplementary script, such as Delivery Script for Queue delivery mode and Timed Notification script for reminders, need to be updated in order to support non-ascii databases. New versions are available for download from [http://store.cqadmin.com/index.php/clearquest.html CQAdmin store]. == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 3ac7c6e41a417b91ac1dc182d31f06314901562b 287 286 2017-04-24T03:35:46Z Paul 1 wikitext text/x-wiki <big>'''Email Notification Package 1.5'''</big> <big>'''Release Notes'''</big> == Enhancements == === Support for Non-ASCII code pages === Safe support of non-ascii code pages was added, with few limitations. ==== Using non-ascii field names ==== Currently, the parser does not provide full support non-ascii characters in field names using variable-like notation. For instance, the following field name would not be recognized: '''${моё_самое_любимое_имя}'''. One of the possible workarounds is to use '''GetFieldValue''' function to access such fields in email notification rules. For instance, in my example, I could use the following syntax: '''GetFieldValue('моё_самое_любимое_имя')''' ==== Using non-ascii characters in message envelope ==== Using non-ascii characters email envelope is permitted. Nevertheless, you might hit some limitations in your environment. Please check the following page for details: [[Email_Envelope_and_UTF-8 | Non-ASCII Characters in Email]]. <br /> == Prerequisites == === ClearQuest client version === The package can be used with ClearQuest 7.0.0 or later. Earlier versions are supported in version 1.5 only. <br /> == Read More == * [[Email_Notification_1.5_Release_Notes | Email Notification Package Release 1.5 Notes]] * [[ClearQuest_Email_Notification_Package | ClearQuest Email Notification Package]] * [[Package_configuration | Package configuration guide]] * [[ClearQuest_Email_Notification_Package_FAQ | Frequently Asked Questions ]] * [[Notification_Examples | Examples]] [[Category:Rational]] [[Category:ClearQuest]] [[Category:Email_Notification_Package]] 2eeede1a09922dbb0f907379a152b3c08ab63d41